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Chapter 1 
The Professional 
Development System 


The Microsoft Macro Assembler Professional Development System is a collection 
of tools designed to increase DOS and OS/2 programming efficiency. The system 
offers 


m The Microsoft Macro Assembler (MASM) 

= A customizable editor that can accept user extensions 
m A source-level, window-oriented debugger 

m A project-management (“make’’) utility 

m A source-level browser 


= Acomplete online reference system 


The Programmer’s WorkBench (PWB) integrates these tools, creating an environ- 
ment in which you can edit, assemble, link, and debug your programs. 


This book is a general introduction to MASM. This chapter introduces some of the 
features of the Professional Development System. Chapter 2 describes how to in- 
stall the Professional Development System. Chapter 3 introduces the Program- 
mer’s WorkBench. Chapter 4 shows how to use the online reference system—a 
complete reference to the Professional Development System and the MASM lan- 
guage that is accessible both within PWB and at the OS/2 or DOS command line. 


NOTE Microsoft documentation uses the term “OS/2” to refer to the OS/2 systems— 
Microsoft Operating System/2 (MS@ OS/2) and IBM 0$S/2. Similarly, the term “DOS” refers 
to both the MS-DOS and IBM Personal Computer DOS operating systems. The name of a 
specific operating system is used when it is necessary to note features that are unique to 
that system. 


The Professional Development System 


If you’d like further information about a topic as you read through this book, you 
can consult 


The Microsoft Macro Assembler Programmer’ s Guide 
The Microsoft Macro Assembler Reference 


The online reference system (discussed in Chapter 4 of this book) 


Before You Proceed 


Before installing MASM, you should make sure that your computer meets min- 
imum system requirements and that your package is complete. 


System Requirements 


MASM requires the following configuration: 


A personal computer running DOS version 3.0 or later or OS/2 version 1.1 or 
later. 


640K (kilobytes) of available memory (RAM) for operating under DOS 
(1 megabyte of RAM is recommended). 


3 megabytes of RAM for operating under OS/2 (4 megabytes are 
recommended). 


At least 384K of extended memory if you want to debug large DOS programs. 


A hard-disk drive with at least 4 megabytes of free space. (The actual space re- 
quired depends on the options you select.) 


A floppy-disk drive. 


Programs assembled with MASM version 6.0 run under DOS versions 2.1 and 
later. 


Package Contents 


Check your MASM package to see if everything is there. If any pieces are 
missing, contact the retailer from whom you purchased the package. 


Features New to Version 6.0 


In the package, you should find the following items: 


Registration card. There are many advantages to being a registered owner of 

MASM 6.0, including notification of future releases and easier access to cus- 
tomer assistance. Please take the time to fill out and mail the registration card 
now. (If you are already a registered owner of an earlier version of MASM, a 
registration card is not included with the update.) 


Disks. The distribution disk labeled “Setup” contains the PACKING.LST file, 

which lists the location and description of all disk files in the MASM package. 

Disk files are compressed; the SETUP program decompresses them as they are 
installed. 


Installing and Using the Professional Development System. The book you’re 
reading. It explains how to install and start to use the Professional Develop- 
ment System. 


Programmer’ s Guide. This book describes MASM features and explains how 
they work. It also shows how to write optimal MASM code. 


Reference. This book describes assembler directives, operators, and instruc- 
tions, including timing and encoding data. 


Product Assistance Request. If you need to contact Microsoft Product Support, 
be sure to fill out this questionnaire (which is bound into the Programmer’ s 
Guide) before calling. 


Documentation Feedback Card. To help Microsoft improve its documentation, 
this postage-paid survey mailer is included in the Programmer’ s Guide. Please 
take the time to fill out the card with any comments or suggestions. 


Features New to Version 6.0 


If you’ve used an earlier version of MASM, you’ll find many new capabilities in 
version 6.0, and you’ll discover that you can perform familiar operations more 
quickly: 


Speed up development with the integrated Programmer’s WorkBench. 


Build programs more easily with the new “make” facility (NMAKE) and 
PWB’s powerful project capabilities. 


The Professional Development System 


m Track down program bugs and logic errors more quickly with the new Micro- 
soft CodeViewe debugger version 3.12. With an 80286 or 80386 processor and 
1 megabyte or more of RAM, you can debug a program up to 640K in size in 
real mode. 


m Access MASM language, assembler, linker, and utility documentation with the 
Microsoft Advisor and QuickHelp online reference systems. 


m Cross-reference program procedures with the PWB Source Browser. 


m Create OS/2 applications with increased support for dynamic-link libraries 
(DLLs), multiple threads, and improved debugging options. 


m Edit source code with PWB’s mouse- and window-oriented editor. 


For a detailed list of new language features, see Appendix A, “Differences be- 
tween MASM 6.0 and 5.1,” in the Programmer’ s Guide. 


Microsoft Programmer’s WorkBench 


The Programmer’s WorkBench can cut development time and increase your pro- 
ductivity. Its integration allows you to edit, build, run, and debug a program 
without ever leaving PWB. Its multiwindow display lets you edit several files at 
once or access online help while still viewing your code. Drop-down menus and 
mouse support let you perform most functions by clicking the mouse on menu 
names or by pressing a few keys. 


The PWB editor is easy to configure and completely extensible. It combines 
powerful features such as macros and regular-expression search capabilities with 
the simplicity of a window-based application (see Figure 1.1). 


The Microsoft Advisor online reference system provides quick access to informa- 
tion about MASM, PWB, CodeView, the assembler, linker, utilities, and even the 
reference system itself. Figure 1.2 shows online information about MASM’s INC 
instruction. 


Microsoft Programmer’s WorkBench 


File Edit View Search Make Run Options Browse 
Ee 1) MASMOONM ISCDEMO..ASM 
>; Preserve original screen and put up window 
; Pass top, left, bottom, right, and attribute 


INVOKE WinOpen, 9, 9, vconfig.rows, 79, O7h 


D:\MASM60O\MISCDEMO .LST 

> Preserve original screen and put up w 
> Pass top, left, bottom, right, and at 
INVOKE WinOpen, 9, 9, vconfig.rows, 79 

xor ax, ax 

push ax 

xor ax, ax 

push ax 

mov al, byte ptr DGROUP: uconf ig+00Zh 

xor ah, ah 

push ax 

mou ax, +00000004Fh 

push ax 

hou ax, +000000007h 

push = ax 

call WinOpen 


EKER KEK KK KK KE 


KFi=Help> <Alt=Menu> <F6=WINDOW> macro [00206 053 


Figure 1.1 Editor Window 


File Edit View Search Make Run Options Browse 
. Help: INC Instruction 
<Detail> <Key> <Example> 4Up> <Contents> <Index> <Back> 


Title: Increment Flags: ODITSZAPC 
Syntax: INC dest + js tt 
See also: DEC, SUB 

Description: 


Adds 1 to the destination operand. Because the operand is treated 
as an unsigned integer, the INC instruction does not affect the 
carry flag. If you need to test the carry flag, use the ADD 
instruction. 

Be 


| D: NMASM6ON\MISCDEMO .ASM i 


WinMsg LLEN3] ; Increment window number 
mou bx, Row1 
add bl, 2 Message row 


ME 00521.0 


Figure 1.2 Help Window 
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When you’re ready to assemble the program, you don’t need to remember the full 
range of command-line assembler options. All options are conveniently located in 
a PWB dialog box where they can be clicked on or off (see Figure 1.3). Setting op- 
tions is simply a matter of using the mouse or keyboard to set case, warning level, 
debug, or release options. 


File Edit View Search Make Run §}80)@ Browse 
D:\MASM6ON\MISCDEMO .ASM 

Macro Assembler Global Options 
Case Sensitivity Warn Level 
) Preserve Case of Names in Jb ject File ( ) Level ¢ 

) Jreserve Case of All User Identifiers ( ) Level 

) Map All Identifiers to Dppercase (+) Level % 
( ) Level & 


° 


( 
( 
( 


Xx] rnings Treated as Errors 
J Wjiny Memory Model 

J] yASM 5.1 Compatibility 

] 


Emulator Fixups for Jloating Point 


[ 
C 
[ 
C 


Daf ines 
clude Paths 
Additional Options [ 
< Set Debulj Options... < Show Debug Options... 
: Po} < Set fJelease Options... < Show Release Options... 


Figure 1.3 Macro Assembler Global Options Dialog Box 


PWB uses the powerful NMAKE tool to speed up development. NMAKE ex- 
amines each module of a program to determine whether changes have been made 
that require the module to be reassembled. NMAKE then automatically assembles 
the modules as necessary and links them. When you’ re ready to build your pro- 
gram, you just select a single menu command to start the process. PWB invokes 
NMAKE and builds an application, using the options you set. 


If warnings or errors occur during assembly or linking, PWB opens a window with 
a full list of assembly or link errors (see Figure 1.4). You can then consult the on- 
line reference system for comprehensive information about each error. 


Microsoft Programmer’s WorkBench 


File Edit View Search Make Run Options Browse 
aD MASMOO\M ISCDEMO .ASM 
cnp uconf ig.rows, 49 > Current mode 50 lines? 
Je toggle25 > Yes? Toggle VGA to 25-line 
cmp uconfig.row, 42 > Current mode 43 Lines? 
jne togg le43 : No? Must be 25 
cmp vconf ig.adapter, EGA > Yes? And is adapter EGA? 
je toggle2s > Yes? Then toggle to 25 line 
nov al, 50 ; No? Toggle VGA to 50 line 
jmp toggle2s 
toggle43: 
nov al, 43 > If currently 25 lines, make 
; either EGA or VGA 43 lines 


toggle2s: 
; Change line mode, pass lines 
INVOKE SetLineMode, ax 


on 


sor TTI 
MISCDEMO .asm(542): error AZOO6: undefined symbol : row 


<Fi=Help> <Alt=Menu> <F6=WINDOW> macro [RRR 00941 .065 


Figure 1.4 Error Window 


Once a program has been successfully built, you can run it from within PWB to 
test it. If you need to make modifications, you can return directly to PWB to make 
the changes. 


Another useful PWB feature is the Source Browser. With the Browser you can ex- 
amine your code and display information about procedure and variable relation- 
ships (see Figure 1.5). This option is helpful for tracking program flow and 
isolating bugs. 


For bugs that are more difficult to locate and understand, use PWB’s Debug Build 
option, then invoke the CodeView debugger directly from PWB. You can step and 
trace through your code at the source level while examining variables, registers, 
and memory (see Figure 1.6). 
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File Edit View Search Make Run Options Biti 


- <browse 
FUNCTION CALLED BY LIST Goto lef inition... 
Goto ljeference... 
@Startup: (MISCDENO .asm) iew Relationship... 
AddLong : (MISCDEMO. asm) List References... 
backspace: Str Input [2] a 
BinToHex: C(MISCDENO.asm)(2Z] ExecP 
blink: SetAttrs([ZyY 
c_and: Colors(3] Next Ctr 1+Num+ 
c_done: Colors[?7] Previous Ctr 1+Nun— 
c_mou: Colors[Z] 
c_not: Colors[3] Case Sensitive 
c_or: Colors[3] +Split Yindous 
c_rol: Colors[3] 
c_ror: Colors{3] 
c_xor: Colors[3] 
ChangeDir : CMISCDENO. 
ChangeDr ive: C(MISCDEMO. 
Checkfnsi : GetConf ig Checkfnsi (MISCDEMO. asm) 
CheckCoproc: GetConf ig CheckCoproc (MISCDEMO .asm) 
CheckPrinter: GetConf ig CheckPr inter (MISCDEMO.asm) 


Figure 1.5 Browser Window 


Once you locate the bug, you can exit CodeView and return directly to PWB, 
where you can fix the error. When the code is completely debugged, you can build 
a final release program using PWB’s Release Build option. 


File Edit View Search Run Watch Options Calls 
—wuatch 


uconf ig.rous = 6x0018 ’ Tt’ 
OldMode = 0x@018 ’T’ 
KeepSeg = OxJ3afd 


— 


nov OldCurs, ax >; Store it 


>; Preserve original screen and put up window 
> Pass top, left, bottom, right, and attribute 
INVOKE WinOpen, 0, 9, vconfig.rows, 79, O?7h 


mou KeepSeg, ax ; Keep segment a 
: > If windou not 
-EXIT 1 ; Exit with retu 
. ENDIF 


-WHILE 


; Display ain menu 


3aFC: 0000 CD 20 E6 SF 00 9A FO FE 1D FO 8B 02 CO 34 51 63 . 
35FC:0016 CO 34 BB OA CO 34 47 1B 01 01 O1 00 02 O03 FF FF .4...4G6 


<F6=Trace> <F10=Step> <F5=Go> <Fé=Window> <F3=Display> 


Figure 1.6 CodeView Window 


Key to Document Conventions 


Key to Document Conventions 


This book uses the following document conventions: 


Example 


COPY TEST.ASM C: 


INVOKE 


expression 


ML /Zi HELLO.ASM 


SHIFT 


“bookmark” 


Programmer’s 
WorkBench (PWB) 


Description 


Uppercase letters represent DOS commands and 
filenames. 


Boldface letters indicate standard features of the 
MASM language: keywords, operators, and stand- 
ard library functions. 


Words in italics indicate placeholders for informa- 
tion you must supply, such as a filename. Italics are 
also occasionally used for emphasis in the text. 


This typeface is used for example programs, pro- 
gram fragments, and the names of user-defined 
functions and variables. It also indicates user input 
and screen output. 


Small capital letters denote names of keys on the 
keyboard. A plus sign (+) indicates a combination 
of keys. For example, SHIFT+F5 tells you to hold 
down the SHIFT key while pressing the F5 key. 


The first time a new term is defined, it is enclosed 
in quotation marks. Since some knowledge of pro- 
gramming is assumed, common terms such as 
memory or branch are not defined. 


The first time an acronym appears, it is spelled out. 


oe SS 
— 


ones 
ees 
ce 


eee 
Ce oe i : a coe 
Or ne > : eee oe — 
: : — : ee Se 


ae 


ao ee = 


ree 
eee 
ee 
SPOUSE EER OG OH 
hee bosier Seneca 
ae ne 


ees 
Seas: 

Hae 

a 


ee: 


Chapter 2 
Installing the Microsoft 
Macro Assembler 


This chapter explains how to install the Microsoft Macro Assembler (MASM), 
configure extended memory for use with the CodeView debugger, and customize 
components of the Programmer’s WorkBench. 


You must run the installation program (SETUP.EXE) to install MASM. The files 
on the distribution disks are compressed; SETUP both uncompresses the files and 
copies them to your hard disk. SETUP runs under both DOS and OS/2. 


Before running SETUP, back up the distribution disks and make sure you have 
enough disk space (at least 4 megabytes, depending on the options you choose) to 
install the Professional Development System. 


Running SETUP 


Insert the disk with SETUP in the appropriate disk drive. Make that drive the cur- 
rent drive. Type SETUP and press ENTER to begin installation. 


If you aren’t sure how you want to set up MASM 6.0, the default responses to 
SETUP’s questions are usually a good starting point. (You can run SETUP again 
at any time to install a different configuration.) Press ENTER to proceed. 


From the Main Menu of SETUP (see Figure 2.1), you can 


m Install the Microsoft Macro Assembler 

m Install the Macro Assembler using defaults 

mw Run SETUP without installing any files 

m View important documentation notes (README.DOC) 
m View the packing list (PACKING.LST) 

m Copy a file from the distribution disks 

m Exit SETUP 


11 


installing the Microsoft Macro Assembler 


Microsoft MASM 6.0 Setup Main Menu 


If this is the first time you have run SETUP, press ENTER now 
to instal] MASM. Or press F1 for more information. 


Install the Microsoft Macro Assembler 


Install the Macro Assembler using defaults 

Run SETUP without installing any files 

View important documentation notes CREADME .DOQC) 
View the packing list C(PACKING.LST) 

Copy a file from the distribution disks 

Exit SETUP 


Use the ARROW (T,4) keys to make the selection, then press ENTER. 


ENTER=Cont inue Tl=Make Selection Fi=Additional Information CTRL+C=Exit 


Figure 2.1 Main Menu of SETUP 


“Install the Microsoft Macro Assembler” is highlighted as the default. If you want 
a different function, use the UP and DOWN ARROW keys to highlight the desired 
function; then press ENTER. 


The first time you run SETUP, press ENTER to begin installation. If you want to be- 
come familiar with SETUP and its options, select the third menu item, “Run 
SETUP without installing any files.” 


The fifth menu item, “Copy a file from the distribution disks,” allows you to trans- 
fer specific files without having to go through the full installation. 


To exit SETUP at any time, press CTRL+C. SETUP never erases files from the dis- 
tribution disks, so you can quit and start over as often as you need to. 


Supplying SETUP Information 
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The SETUP screens following the Main Menu request information about your 
operating system, hardware configuration, and directory paths. After you have an- 
swered all the questions, SETUP begins transferring files to your hard disk. 


Most questions (such as which operating system you’re working under or whether 
you use a mouse) have a limited number of specific. responses. These are listed in 
a box, with the default response highlighted. The following sections provide infor- 
mation about individual SETUP questions. 


Responding to the Prompts 


If you want to accept the default response, press ENTER. If not, use the UP and 
DOWN ARROW keys to select a different response; then press ENTER. In either case, 
pressing ENTER advances you to the next screen. 


The remaining questions prompt you for the directories in which the assembler, 
linker, debugger, include files, and other files are to be placed. SETUP suggests a 
default path, which you can accept by pressing ENTER. 


If you don’t want to use the default directory, use the BACKSPACE key to erase it; 
then type in the directory you want. (You can also change the hard-disk specifica- 
tion if you want to install MASM 6.0’s components on different drives.) Press 
ENTER to accept the directory and advance to the next screen. 


If you specify a directory that does not exist, SETUP automatically creates it for 
you. Therefore, be careful to enter the correct directory name. 


Changing Your Response 


You can change responses as often as you like before pressing ENTER and moving 
to the next screen. Don’t worry if you make a mistake or change your mind. The 
last screen of SETUP displays all the options you have selected; you can change 
any of them before the installation actually begins. 


Responding to the Prompts 


The SETUP questions are largely self-explanatory. The following sections supply 
additional information that might be useful to you. 


Choosing the Host Operating System 


There are two versions of MASM;; one runs under DOS and the other under OS/2. 
Select the versions for the operating systems you use. If you want to run MASM 
under both DOS and OS/2, you can install both. 


MASM can create executable files for OS/2 or DOS, regardless of which operat- 


ing system the assembler runs under. Programs must be debugged and run under 
the operating system they were written for. 
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Installing the Programmer’s WorkBench (PWB) 


PWB integrates editing, assembling, linking, and debugging to speed program 
development. You can customize the PWB editor to accommodate your own work- 
ing style and needs. 


Installing the Programmer’s WorkBench is optional. You can call the assem- 
bler and linker from the command line, and run CodeView and the other tools 
separately. 


Emulating BRIEF 


If you install PWB, you can choose to configure the PWB editor so that most of its 
editing functions are assigned to the same keystrokes that the BRIEF editor uses. 
If you decide not to configure PWB this way during installation, you can add these 
(or other) customizations later. 


Installing the New MASM.EXE Utility 


MASM version 6.0 now includes ML.EXE, which replaces MASM.EXE. The 
ML.EXE utility both assembles and links, making the assembler’s behavior identi- 
cal to that of Microsoft compilers (such as CL.EXE for C and FL.EXE for FOR- 
TRAN). You can still assemble without linking by adding the /c option to the 
ML.EXE command line. 


To simplify the transition from previous versions of MASM to MASM version 
6.0, Microsoft has provided a special MASM.EXE utility. The new MASM.EXE 
is not an assembler. It simply translates the old-style command line into the new 
format and passes the command to ML.EXE. 


Since MASM.EXE also sets certain options, you may want to look at Appendix A 
in the Programmer’ s Guide, “Differences between MASM 6.0 and 5.1,” before 
using MASM.EXE. This appendix lists all the new and changed features in 
MASM 6.0 and gives recommendations for updating existing code. 


Copying Documentation Files and Sample Programs 


Having SETUP copy documentation files and sample programs to your hard disk 
makes them available at any time. You can load them into PWB or a text editor, or 
print them for convenient reading. You can also read the documentation files from 
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within SETUP by selecting the “View important documentation notes” option 
from the function screen. 


Only the README.DOC and the PACKING.LST files can be copied directly 
from the distribution disks without SETUP. From the Main Menu in SETUP, you 
can also select the “Copy a file from the distribution disks” option. This decom- 
presses and copies files to the current directory. 


Copying the Microsoft Mouse Driver, MOUSE.COM 


If you choose DOS as the host mode, you are asked if you want to copy the most 
recent version of the Microsoft mouse driver, MOUSE.COM. (The mouse inter- 
face is built into the OS/2 environment.) This driver is written for the Microsoft 
Mouse, but it will work with any 100%-compatible mouse or pointing device. 


If you currently use a Microsoft Mouse, you already have a mouse driver on your 
hard disk. SETUP places the mouse driver in the directory for real-mode files that 
you specify later. This directory is probably not the location of your current mouse 
driver. If you want to use the new driver, be sure to copy it to the appropriate 
directory after you leave SETUP. 


Choosing the Target Hard Disk 


Specify the hard disk on which you want to install the Professional Development 
System. It becomes the default drive for the directories SETUP will suggest later 
on. However, if you want to install the Development System components on more 
than one drive or partition, you can change the drive designation in the suggested 
directories. 


Choosing Bound, Real-Mode, and 
Protected-Mode Directories 


Some of the software supplied with the Professional Development System is 
“bound,” which means it runs under DOS or OS/2. However, five system com- 
ponents come in two versions: one for DOS (or OS/2 real mode), the other for pro- 
tected mode for OS/2. These components are ML, PWB, NMAKE, QH, and 
CodeView. 


If you set up for only one mode, it doesn’t matter where you place these com- 


ponents. However, ML, PWB, QH, and NMAKE use the same name for their real- 
and protected-mode versions. If you set up for both real and protected mode, you 
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cannot place these components in the same directory, because you cannot have 
two identically named files in the same directory. 


Therefore, SETUP requires that you select different directories for the bound, real- 
mode, and protected-mode components. If you change SETUP default directories, 

be sure you don’t choose the same directory for both the real- and protected-mode 

components. 


Note that if you have chosen to install only for DOS or OS/2 real mode, you are 
not prompted for a protected-mode directory. Likewise, if you have chosen to in- 
stall only for OS/2 protected mode, you are not prompted for a real-mode directory. 


Selecting File Directories 


SETUP wants to know where to place help, include, initialization, and library files 
(in OS/2). The corresponding environment variables in your AUTOEXEC.BAT or 
STARTUP.CMD file should point to the correct directories. This is explained in 
the section called “Configuring Your System,” later in this chapter. 


Reviewing and Changing Responses 


Installing 
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The Status and Change screen is the last screen before SETUP actually begins in- 
stallation. This screen displays all your responses. If you are satisfied, press ENTER 
to select the “No Changes” default, and installation will begin. 


If you want to change a response, press the DOWN ARROW key to move the 
highlight to the appropriate line; then press ENTER to display the screen that con- 
trols this response. Change your response; then press ENTER again to return to the 
status and change screen. Your new response for that option is now displayed. 


You can repeat this process as often as you want. When all options are the way 
you want them, select “No Changes” and press ENTER to begin installation. 


SETUP checks to see if your system has adequate space available and then 
prompts you for each distribution disk it requires. The only likely error is inserting 
the wrong disk. If this occurs, SETUP prompts you for the correct disk. 


Configuring Your System 


Configuring Your System 


At the end of installation, SETUP creates system-configuration files. These are 
listed in Table 2.1, along with SETUP’s default directories: 


Table 2.1 SETUP Configuration Files 


Operating System Configuration Files Default Directory 
DOS or OS/2 real mode NEW-VARS.BAT, C:\MASM\BIN 
NEW-CONE.S YS 
TOOLS.PRE C: \MASM\INIT 
OS/2 protected mode NEW-VARS.CMD C: \MASM \ BINP 
TOOLS.PRE C: \MASM\ INIT 


If you add the contents of these files to your AUTOEXEC.BAT (or 
STARTUP.CMD), CONFIG.SYS, and TOOLS.INI files, your system will be cor- 
rectly configured for MASM each time you start your computer. You can also run 
NEW-VARS.BAT or NEW-VARS.CMD to set environment variables before you 
run MASM. 


Modifying AUTOEXEC.BAT or STARTUP.CMD 


The NEW-VARS.BAT and NEW-VARS.CMD files contain commands that set 
environment variables. Insert these commands in the AUTOEXEC.BAT or 
STARTUP.CMD file. All changes to environment variables are prefixed to the cur- 
rent settings. Table 2.2 explains these variables. 


Table 2.2 Environment Variables 


Variable Description 

ASMEX Location of assembly-language example files 
HELPFILES Location of help (.HLP) files 

INCLUDE Location of include (.INC) files 

INIT Location of initialization (.INI) files 

MASM, ML List of command-line options requested 
PATH Path to search for executable files 

QH Location of QuickHelp help (.HLP) files 
TMP Location of PWB/LINK temporary files 
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The online reference system searches for help files in a specific sequence. There- 
fore, do not modify the HELPFILES variable unless you are familiar with the 
search sequence. Changing this path might make the online reference system 
inaccessible. 


Modifying CONFIG.SYS 


If the host operating mode is OS/2 real mode or DOS, check the values of files 
and buffers in CONFIG.SYS. The values in NEW-CONF.SYS are min- 
imums; the CONFIG.SYS values should be at least as large. 


Under OS/2, be sure the LIBPATH variable includes the directory of the help sys- 
tem’s dynamic-link library MSHELP.DLL. OS/2 users who want to use CodeView 
must also include the statement IOPL=YES. 


To use the extended memory features of CodeView under DOS, you must use the 
HIMEM.SYS driver supplied with this product. Add DEVICE=HIMEM.SYS to 
CONFIG.SYS. Be sure to specify HIMEM’s full path. See the section later in this 
chapter called “Configuring Extended Memory for CodeView” for additional 
information. 


Modifying TOOLS.INI 


The TOOLS.PRE file contains additional PWB configuration settings. Add the 
contents of TOOLS.PRE to your existing TOOLS.INI file. If you don’t already 
have a TOOLS._INI file, rename TOOLS.PRE to TOOLS.INI. 


PWB looks for TOOLS.INI in the directory containing PWB. If you move 
TOOLS.INI to another directory, specify its path inthe INIT environment varia- 
ble in your AUTOEXEC.BAT or STARTUP.CMD file. 


Customizing the Programmer’s WorkBench 


The TOOLS.INI file controls many configuration options for MASM 6.0 utilities. 
These options let you customize the following: 


PWB 
CodeView debugger 
Microsoft Advisor online reference system 


NMAKE utility 


You can modify the TOOLS.INI settings with the PWB editor or any word proces- 
sor. These are some of the options you can change: 


Screen colors and the number of lines displayed by PWB 
Macros for PWB 

Key assignments for PWB 

Default key settings for PWB 

Location of help files used by the online reference system 


Options for NMAKE 


TOOLS.INI is described in the online reference system. See Chapter 14 of the 
Programmer’ s Guide for more information about customizing PWB. 


Customizing the Programmer’s WorkBench 


There are other ways to customize PWB besides editing the TOOLS.INI file. For 
example, you can control a variety of editor functions and options from within 
PWB with the Editor Settings command from the Options menu. 
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For more information about customizing the Programmer’s WorkBench, see 
Chapter 3 in this manual, and Chapter 14 of the Programmer’ s Guide, “Custom- 
izing the Microsoft Programmer’s WorkBench.” For more information about 
customizing NMAKE and other utilities, see the online reference system or the 
Programmer’ s Guide. 


Configuring Extended Memory for the CodeView 
Debugger — 


Extended memory is the memory above the first megabyte that an 80286, 80386, 
or 80486 can access in protected mode. (Extended memory is not the same as 
expanded memory. Expanded memory is bank-switched memory that overcomes 
the 640K RAM limit of machines with 8086/8088 processors.) 


To use the extended memory features of the CodeView debugger under DOS, you 
must firstadd DEVICE=HIMEM.SYS (with HIMEM’s full pathname) to the 
CONFIG.SYS file, then reboot. The NEW-CONEF.SYS file created by SETUP con- 
tains a sample HIMEM entry. 


NOTE HIMEM.SYS implements the XMS 2.x standard. The complete XMS source and 
specification are available from the Microsoft Information Center. 


There are several additional factors to consider when using extended memory with 
CodeView under DOS or Windows: 


m CodeView needs at least 384K of extended memory. If you add memory to 
your computer, be sure to configure at least 384K of it as extended memory. 


m Older versions of HIMEM.SYS may not work properly with this product. Use 
_the version of HIMEM.SYS on the MASM 6.0 distribution disks. 


m Other memory managers such as 386-Max or QEMM may conflict with 
HIMEM.SYS. Don’t install more than one memory manager. 


m Don’t use HIMEM.SYS (or any other memory manager) with Windows/386. 
Windows/386 allocates extended and expanded memory automatically. 
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mw If you run Windows 3.0 in 286-Protected mode, create a PIF for CodeView 
and specify at least 384K of XMS (extended) memory. 


m Many RAM-disk and disk-cache programs are incompatible with 
HIMEM.SYS. The RAMDRIVE and SMARTDRYV programs supplied on the 
distribution disks are HIMEM.SYS-compatible. 


mg If yourun TSRs, check their documentation to see if they are compatible with 
HIMEM/XMS 2.x. If there is any question about compatibility, manually in- 
stall one TSR at a time. 


SETUP places the HIMEM, RAMDRIVE, and SMARTDRYV drivers in the 


C:\ MASM\BIN directory or in the directory you have specified for real-mode 
executable files. 
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Chapter 3 
Using the Programmer's 
WorkBench 


The Programmer’s WorkBench (PWB) is a window-oriented programming en- 
vironment that incorporates a text editor, an assembler, a linker, a debugger, a 
make utility, a source-code browser, and an online reference system. It is an 
alternative to switching between command-line-based programs: you can edit, 
assemble, link, and debug without leaving this integrated environment. To demon- 
strate PWB’s features, this chapter includes a sample program that you can as- 
semble, link, and debug. 


This chapter explains how to start PWB and then introduces the following PWB 
elements: 


m Windows and menus. You can quickly find the command you need using the 
menus. The section “Using Windows and Menus” explains how to open and 
close windows and how to navigate through the menus. 


m= Programmer’s editor. Features such as “bookmarks,” macros, customized key 
commands, and enhanced search capabilities decrease the amount of time you 
spend writing code. 


m= Integrated assembler and linker. You can assemble, link, and run a program 
without leaving the editor. PWB’s integrated environment and project- 
management facilities save you hours of development time. 


= Integrated browser and debugger. Using the Source Browser, you can quickly 
find a data declaration or procedure definition in your source code, as well as 
references to all procedures and variables in the program. With the CodeView 
debugger, you can set breakpoints, examine variables and machine registers, 
and step through execution of your program one line at a time. 
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Starting PWB 


To run PWB, type 
PWB 


at the command line. You can immediately begin entering source code in the un- 
titled window that appears. PWB maintains a history of the files you have opened. 
The next time you run PWB, it opens the last file you worked on. 


Specifying a Source File 


You can open an existing source file by specifying its name or pathname after the 
PWB command. If PWB can’t find the specified file, it asks if you want to create a 
new file with that name. You can also open an existing source file with the Open 
command from the File menu. 


Command-Line Options 


PWB offers a number of command-line options that can configure PWB, position 
the file at a bookmark, or perform user-selected functions automatically. These are 
documented in the Reference and in the “Starting PWB” topic in online help. 


Elements of the PWB Environment 


This section introduces the PWB environment and describes how to control win- 
dows and choose commands from the menus. It also describes elements within the 
PWB environment. 


You can enter PWB commands from the keyboard or with a Microsoft (or fully 
compatible) Mouse. Unless the right mouse button is specifically mentioned, 
“clicking” means to press and release the left mouse button once. 


Windows and Other Screen Elements 
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Figure 3.1 shows the components of a typical PWB screen. Some elements pro- 
vide information only. For example, if CAPS LOCK is on, the letter C appears in 
the lower-right corner of the screen. Other elements perform actions triggered by a 
specific keystroke or mouse action. For example, if you click the button in the 
upper-left corner of a window with the mouse, the window closes. 


Elements of the PWB Environment 


Close button Menu bar Maximize button 


File Edit View Search Make Run Options Browse 

s D:\MASM60NHELLO .ASM 

> HELLO.ASM defines a string and calls the procedure PutStr to 
3; display the text. PutStr is in a separate module PUTSTR.ASM. 


-MODEL small, c 


3; Tell assembler PutStr’s argument type and how to call PutStr: 
PutStr PROTO pMsg:PTR BYTE 


. DOSSEG 
- STACK 


D:\MASM6O\PUTSTR .ASM 
PUTSTR.ASM contains a procedure|PutStr, which displays a 
null-terninated string on the s¢reen. 


-MODEL small, c 


- DATA 
vid_conf ig STRUC 
mode BYTE 
dpage BYTE 


001 
; ‘ 
Reference bar Title bar File-type Line and column 
Window indicator indicators 
Scroll bars Status indicators 
Figure 3.1 Parts of a Screen 
The parts of a PWB screen and their uses are listed in Table 3.1. 
Table 3.1 Parts of a PWB Screen 
Name Use 
Menu bar Lists names of available menus. 
Close button Closes window (appears only if more than one window is 
displayed). 
Title bar Shows name of file currently being edited. 
Windows Contain source code or display information associated with on- 
line help. 
Maximize button Enlarges or restores window to its original size. 
Scroll bars Indicate cursor position in the current file and allow cursor 
movement. 
Reference bar Lists shortcut keystrokes (keyboard users) and direct PWB com- 


mands (mouse users); summarizes menu contents and displays 
other information. 
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Table 3.1 (continued) 


Name Use 

File-type indicator Tells type of file. ASM: MASM source code; text: any 
other user-created file; pseudo: file-like means of displaying 
data. 

Line and column indicators Show current line and column of text cursor. 


Status indicators : Meta prefix is set. 

: Background assembly in OS/2. 

: CAPS LOCK is on. 

: Carriage return isn’t used to terminate a line. 
: File has been modified. 

: NUM LOCK is on. 

: Overtype is on. 

: File is set to Read Only status. 

: File is temporary. 

: Amacro is being recorded. 


<A wWOoOAZAz Sr owv> 


Menus 


PWB commands are organized into menus whose names appear in the menu bar. 
A brief description of the selected menu appears in the reference bar. To get more 
information about a menu; select the menu and press F1, or point the mouse cursor 
at the menu name and click the right mouse button. 


PWB has the following menus: 


File Menu 
New Clears the Source window to start a new file 
Open Loads an existing source file 
Merge Merges one or more files with the current 
file 
Next Displays the next file in the file list spec- 


ified at start-up 


DOS SJell Shift+F9 


Save Saves the current file 

Save As Saves the current file under a different name 
Save All Saves all modified files 

Close Closes the current file 
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Print Prints a selection or the current file 
DOS Shell Temporarily exits to DOS or OS/2 
Exit Leaves PWB 


At the bottom of the File menu, PWB displays a list of recently opened files. This 
helps you access the files you’ve been working with. 


Edit Menu 


Undo Reverses the effect of your recent edits 
Redo Reverses the effect of the last Undo 
command 
Shift+Del 
Ctr1+Ins Repeat Repeats your last edit 
Shift+Ins 
Del Cut Deletes a selected block of text from the ac- 
Set Jnchor tive window and copies it to the clipboard 
Select To Anchor . 
Paste Inserts a selected block of text from the clip- 
oad his board into the active window 
Clear Deletes selected text without copying it to 
the clipboard 
Set Anchor Saves the current cursor position as a refer- 
ence point for text selection 
Select to Highlights text from the previously set an- 
Anchor chor to the current cursor position 
Box Mode Toggles text selection mode between box, 
line, and stream modes 
Read Only Makes all files read-only (to protect from 
accidental modification) 
Set Record Defines a macro name and its shortcut key 
Record On Records keystrokes for a macro 
Edit Macro Edits a recorded macro 
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View Menu 


Split jae ical 


eo Window Ctr1+F6 


ximize Window Ctrl+Fi0 
lose Window Ctr1+F4 


Cimpile Results 


Search Menu 


Search 


Selected Text F3 

lNepeat Last Find F3 
ange... 

For File... 


Shift+F3 
Shift +F4 


Next Error 
Previous Error 
Set Error 


To Mark... 
Wefine Mark... 


Set Jark File... 
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Split Horizontal 
Split Vertical 
Size Window 


Maximize 
Window 


Close Window 


Compile 
Results 


Find 
Selected Text 
Repeat Last 
Find 


Change 


For File 
Next Error 


Previous Error 


Set Error 


Go to Mark 


Divides the active window horizontally. 
Divides the active window vertically. 
Enlarges or shrinks the active window. 


Toggles between Maximize Window and 
Restore Window. (Maximize Window en- 
larges the active window, while Restore 
Window restores it to its original size.) 


Closes the active window. 


Shows the result of the last compilation. 


Searches for the next occurrence of a text 
string in the active window 


Searches for the next occurrence of the cur- 
rent selection 


Repeats the search without retyping the text 
string 


Searches for one text string and replaces it 
with another 


Searches for a file on disk 
Moves to the next build error in source code 


Moves to the previous build error in source 
code 


Selects the error at the cursor as the current 
error (i.e., synchronizes active window and 
error window) 


Moves the cursor to a “bookmark” (a pre- 
viously specified position in a file) 


Elements of the PWB Environment 


Make Menu 


Build Target... 


Set Program List... 
Edit Program List... 
Clear Program List 


Run Menu 


Command oR 


Debug : 


un DOS Command... 
stomize Menu... 


Define Mark 


Set Mark File 


Compile File 
Build 


Rebuild All 


Build Target 


Set Program List 


Edit Program List 


Clear Program List 


Execute 


Command Line 


Debug 


Run DOS 
Command 


Customize Menu 


Creates a bookmark by associating a name 
with a position in a file 


Creates a file in which you can save book- 
marks or open an existing bookmark file 


Compiles the current source file 


Compiles and links all modified files in a 
multimodule program 


Compiles and links all files (even those that 
have not been modified) 


Builds a single target from the program list 
or non-PWB makefile 


Creates or opens a program list file, which 
defines the components of a multimodule 
program 


Changes the contents of a program list 


Removes the current program list from 
memory, but does not change its contents 


Runs the current program 


Specifies commands that will be supplied to 
your program when you choose Execute or 
Debug from the Run menu 


Invokes the Microsoft CodeView debugger 


Performs any single DOS or OS/2 task 
without exiting the environment 


Adds commands to the Run menu 
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Options Menu 


Options 


ea Assignments... 


Editor Jettings... 
Buil] Options... 


Browse Options... 


JASN Options... 


WINK Options... 
AKE Options... 
CodeJiew Options... 


Environment Specifies the paths to search for include 


files, libraries, and online help 


Key Assignments Assigns keystrokes that invoke commands, 


macros, and extension functions 


Editor Settings Changes the setting of any editor switch 


Build Options Sets the main language, determines what 


type of program is built, specifies whether 
the program is built as a debug or release 
version, and saves current build options 


Browse Options Defines the way the PWB Source Browser 
database is built 
MASM Options Sets compiler options for your project 
LINK Options Sets linker options for your project 
NMAKE Options Sets the command line for NMAKE 
CodeView Options Controls how CodeView uses memory, dis- 
plays information, and handles display of 
output 
Browse Menu 
Goto Definition Locates the definition of any pro- 
gram symbol in your source code 
oe eee Goto Reference Locates the references to any 
Call Tree... name in the source database 
Outline... 
Wake Beanie View Relationship — Queries the PWB Source Browser 
Previous Ctr1+Num- database 
HtASe Oris TELUS List References Displays a list of functions that 
*Split Windows : 
call each function and use each 
variable, type, and macro 
Call Tree Views which functions call other 
functions 
Outline Displays a program outline 
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Next Finds the next definition or next 
reference 


Previous Finds the previous definition or 
reference 


Case Sensitive Defines whether or not your 
searches will be case sensitive 


Split Windows Determines how the Browser 
appears 


Help Menu 


Index Displays a list of indexes for the online 
reference 


pic: Fi 


ip on Help Contents Displays a table of contents for subjects 
t 


Next: covered by the online reference 


Topic Displays information about the item or key- 
word on which the cursor is positioned 


Help on Help Explains how to use the help system 


Next Displays the next piece of information in 
the help system on the topic you looked at 


Choosing Menu Commands 


Keyboard > To choose a command: 


1. Press the ALT key to activate the menu bar. 


2. Press the highlighted character in the menu name (such as F for File), or use 
the RIGHT and LEFT ARROW keys to select a menu. Press ENTER. 


3. Press the highlighted character in the command name (such as S for Save in the 
File menu), or use the UP and DOWN ARROW keys to highlight the command 
and then press ENTER. 


Mouse a To choose a command: 


1. Open the menu by clicking the menu name. 


2. Click the command. 
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If you open a menu and then decide you don’t want to issue a command, there are 
three ways to close the menu: 


m Press the ESC key. 
m Click the mouse outside the menu. 


m Press ALT twice. 


Using Shortcut Keys 


Some menu items are followed by the names of keys or key combinations. You 
can press these “shortcut keys” to execute these commands immediately, instead 
of selecting them from a menu. 


The reference bar at the bottom of the screen also displays commonly used short- 
cut keys. You can click any of these buttons to execute the indicated command. 
Many other shortcut keys have been assigned than are listed on menus. Assign- 
ments are also redefinable. See the Key Assignments option in the Options menu. 


Shaded Commands 


When a menu command is gray (rather than black), it is currently unavailable for 
use. For example, when PWB is first run and no programs have been assembled or 
linked, the Next Error and Previous Error commands in the Search menu are both 
disabled and are therefore shaded gray. 


Ellipses and Dialog Boxes 


A command followed by an ellipsis (...) needs more information before the com- 
mand is executed. You enter this information in a dialog box that appears when 
you select the command. (A command not followed by an ellipsis executes imme- 
diately.) Figure 3.2 shows the dialog box opened by the Find command from the 
Search menu. 


Elements of the PWB Environment 


File Edit View iiaxgai Make Run Options Browse 


D: \MASM6O\M ISCDENO .ASM 
.CODE 
. STARTUP Find 
Find ext: CINVOKE 
3; Initializ 
INVOKE Ini 


> Return un] [ J Wegular Expression 
; Pass PSP [X] trap Around 
INVOKE New 


[xX] fs Sensitive 
' 


> Initializ <files...> 
INVOKE Get 
Q@ OK § <Cancel> < Jelp > 
mov al, 
mov OldMode, al > Preserve original line mode 


> Get current cursor position 
INVOKE GetCurPos 


mov OldCurs, ax ; Store it 


F1=Help Enter Esc=Cancel Tab=Next Field 


Figure 3.2 Dialog Box for the Find Command 


Dialog boxes can contain any or all of the items in the following list. Press ALT 
and the item’s highlighted letter, or the TAB or SHIFT+TAB keys to move among 
items in a dialog box. You can set dialog items from the keyboard or with the 


mouse. 

Item Description 

Option Buttons (¢) Offer a list of choices; only one option can be 
chosen. Use the ARROW keys to move between the 
choices. In Figure 3.2, three option buttons set the 
direction of the search (Forward, Backward, Find 
All). 

Check Box [X] A yes/no switch. If the box is empty, the option is 
turned off. If it contains the letter X, the feature is 
on. Press the SPACEBAR or use the UP and DOWN 
ARROW keys to turn a check box on or off. 

Text Box [.......... ] Accepts text that you type. In Figure 3.2, Find Text 
requires you to type the text to search for. 

List Boxes Certain dialog boxes display lists of information 


(such as the contents of the current disk directory) 
within a list box. If the number of items exceeds the 
list box space, press the ARROW keys, PGUP/PGDN, 
or click the scroll bar to move around the list. 
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Item Description 
Command Buttons Confirm the settings you have entered and which are 
<OK > now enclosed by angle brackets. The OK button 


uses the current settings. The Cancel button exits the 

dialog box and does not change the current settings. 

If one of the command buttons is highlighted, press 

ENTER to execute that command. Clicking a com- 

mand button also executes the command. If a button 

contains an ellipsis, it indicates that another dialog 
‘box will appear when the command is selected. 


Dialog boxes usually contain shortcut keys. Shortcut keys are identified by 
highlighted letters. 


Getting Help 
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PWB uses the Microsoft Advisor online reference system to provide information 
about PWB, the assembler, the linker, the CodeView debugger, other utilities, and 
topics relating to the MASM language. Information can be displayed at any time 
and at any point in PWB or CodeView. For a complete discussion of the online ref- 
erence system, see Chapter 4. 


Menu Help 


To get information about a PWB menu command, choose the command with the 
ARROW keys, then press F1; or point the mouse cursor at the menu command and 
click the right mouse button. A help window appears with information about the 
command. 


Dialog-Box Help 


Many dialog boxes have a help button that provides additional information about 
the dialog box and its contents. To display the information, click the help button 
with the mouse or press F1. 


Using the Editor 


The Help Menu 


The commands in the Help menu can display a table of contents, an index of all 
help topics, and help on using the online reference system itself. 


The Contents command displays the contents of the entire reference system. Infor- 
mation is organized by topic, such as PWB, CodeView, the MASM language, and 
specific utilities. Click a topic to move to that topic’s table of contents. 


The Index command displays every available item in the reference system, organ- 
ized alphabetically. Select the first letter of the topic you want from the alphabet 
bar at the top of the screen. Then select the specific topic from the list that appears. 
Use PGUP, PGDN, and the ARROW keys to scroll through the topics. 


The Help on Help command provides a brief overview of how to navigate through 
the help system and invoke help on any topic. 


Using the Editor 


The program editor is an important part of the PWB environment. This section pro- 
vides a brief overview of its major functions and assumes you are using the default 
key assignments. For a complete list of editor commands and functions, refer to 

the following online reference topics, available on the PWB Contents screen: 


m “Function Quick Reference” 


m “Using PWB Functions” 


Moving Around in a Text File 


Most of the cursor-control keys position the cursor and modify the display just as 
you would expect them to. The HOME, END, PGUP, PGDN, and ARROW keys behave 
as they do in most other text editors. 


If you click in the shaded area on either side of the scroll box in the scroll bar, you 
move the cursor one full window at a time. If you click the scroll-bar arrows, you 
move the cursor one row or column in the corresponding direction. If you click 
and drag the scroll box, you move the cursor to the corresponding relative position 
within the file. 
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Keyboard e 


Mouse 


> 


Defining a Block of Text 


One of the most common editing tasks is defining a block of text, usually before 
deleting, moving, or copying it. 


To define a block of text: 


1. Move the cursor to the beginning of the block. 


2. Hold down the SHIFT key and use any cursor-movement key (ARROW, HOME, 
PGDN, and so on) to move to the end of the block. 


To define a block of text: 


1. Click the first character at the beginning of the block. Continue pressing the 
left mouse button. 


2. Drag the mouse to select the rest of the desired text. The block remains 
selected until you press a cursor movement key or click the mouse again. 


NOTE As |ong asa block is defined, anything you type deletes the defined block and in- 
serts the typed characters. 


As you move the cursor or mouse to define a block, you usually select all charac- 
ters from the starting cursor position to the ending cursor position. This is called 
“stream mode” and is the default. The Edit menu offers three text-selection modes: 


m Stream mode selects all text from the starting cursor position to the ending cur- 
sor position (the default). 


m Box mode selects text from a rectangle whose opposite corners are the starting 
and ending cursor positions. 


m Line mode selects full lines of text from the line with the starting cursor posi- 
tion to the line with the ending cursor position. 


You can select a different mode from the Edit menu. The mode displayed in the 
menu is the next available text-selection mode (not the current mode). You can 
also move through the selection modes during text selection by clicking the right 
mouse button while you hold down the left mouse button. 


Once a block is defined, press DEL to erase it. You can also place the block in the 
clipboard buffer for later use. Press CTRL+INS to copy the block to the clipboard. 


Using the Editor 


Press SHIFT+DEL to copy the block to the clipboard and erase it from the screen. 
Press SHIFT+INS to insert the current contents of the clipboard at the cursor. 


Setting Bookmarks 


A “bookmark” is a permanent marker that lets you quickly return to a specific sec- 
tion of text. A bookmark stays with the text it marks, even if the text is moved. 


To set a bookmark, first position the cursor at the location you want to mark. Then 
select the Define Mark command from the Search menu. 


In the dialog box that appears, type the name you want to give the bookmark. (The 
source filename and the row and column are already entered.) Press ENTER to save 
the bookmark for the current session. To save a bookmark for later editing ses- 
sions, use the Add To Mark File option. The Set Mark File command from the 
Search menu reloads previously saved bookmarks. 


To move the cursor to a bookmark, choose the Go To Mark command from the 
Search menu. A list of all bookmarks is displayed. Select the bookmark from the 
list using the ARROW keys, or click the selected bookmark with the left mouse but- 
ton. Press ENTER to go to the bookmark. 


Setting Anchors 


An “anchor’’ temporarily marks the beginning of selected text. It is most often 
used to define a block that extends beyond the current screen. 


To set an anchor, move the cursor to the desired location and choose the Set An- 
chor command from the Edit menu. Use the Select To Anchor command from the 
Edit menu to select all text between the current cursor position and the anchor. 
Only one anchor can be set at a time. 


Searching for and Changing Text 


You can search for a string of text using the Find command in the Search menu. 
Type the string you want to look for, then use the check boxes to set options such 
as wrap-around search and case sensitivity. The Files button allows you to specify 
a list of files to search through for the designated string. 


Once a string has been located, use the Repeat Last Find command in the Search 
menu (or press the shortcut key, F3) to move to the next occurrence of the string. If 
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you specified several files to search, press SHIFT+F3 to move to the next file that 
contains that string. 


To modify several instances of a string in the source file, use the Change com- 
mand in the Search menu. Enter the target string, the replacement string, and the 
search options. 


PWB also supports searching for and replacing text patterns using regular-expres- 
sions. You can use either the UNIX or Microsoft regular-expression syntax. For 
further information, see the online reference system. 


PWB can also search for selected text in files not currently loaded. Select the Files 
command in the Find dialog box. From the File List box, select the name of a file 
that you want to search. Then click the Add/Delete button to place it in the File(s) 
Selected box. Repeat this step for all the files you want to search. 


You can also enter a wildcard pattern in the File Name text box, and then use the 
Add Pattern button to place it in the File(s) Selected box. Press ENTER or click the 
OK button to begin the search. Use the Next Error and Previous Error commands 
to scan any text that is found. 


Creating Macros 


You can save blocks of text or frequently performed editing tasks as macros. Each 
macro is assigned a key combination that “‘plays back”’ the text or task. 


For example, if several programmers are working on a file and need to keep track 
of who made what changes, a macro can be used to insert a comment with the pro- 
grammer’s name. 


To create such a macro, use the Set Record command from the Edit menu to enter 
a macro name and its associated key combination. For this example, call the macro 
modname and assign it to the key combination CTRL4+J. 


Now choose the Record On command from the Edit menu. A bullet appears to the 
left of the menu command and an X appears in the status line, indicating that all 
keystrokes and menu commands are being recorded. Then type the following: 


; j. courtney coded this 


To stop the recording, choose Record On again, which causes the bullet to disap- 
pear. This action associates all recorded actions with the previously selected macro 
name. Now, each time you press CTRL+J, the comment you typed is inserted at the 
cursor position. 


USINg the cuiur 


Macros are saved in the TOOLS.INI file when you save the <record> pseudofile. 
You can change or delete them by modifying the file. See the section “Customiz- 
ing PWB” in the online reference system for additional information about macros. 


Customizing the Editor 


You can modify editor settings, assign keyboard commands, and emulate com- 
mand sets from other editors to make the editor work the way you like. See the on- 
line reference system and Chapter 14, “Customizing the Microsoft Programmer’s 
WorkBench,” in the Programmer’ s Guide for complete details. 


Changing Editor Settings 


The PWB editor has a variety of settings you can customize, such as word wrap, 
color, and width of tab stops. 


View or modify the settings by choosing the Editor Settings command from the 
Options menu. The editor settings appear in a new window labeled “Current As- 
signments and Settings.” The format is setting:value, where setting is the name of 
the setting, and value is a Boolean, numeric, or text value. You can learn about a 
setting by positioning the cursor on it and pressing F1. 


To change a setting, simply overtype the old value with a new one. The change 
does not take effect until you move the cursor to a different line. To save the 
changed assignments, press SHIFT+F2 (if the default keyboard assignments are in 
effect) or choose the Save command in the File menu. If you do not save, the as- 
signments are temporary and last only for the duration of the PWB session. 


To return to your source file, press F2. 


Modifying Keyboard Assignments 


Most editor functions (such as delete, home, and copy) are already assigned a 
keystroke combination for direct execution. You can reassign these functions to 
different keystrokes by choosing the Key Assignments command in the Options 
menu. 


This command displays the current assignments on a screen labeled “Current 
Assignments and Settings.” Function assignments appear in the format 
function:keyname. You can learn about a PWB function by positioning the cursor 
on the function name and pressing Fl. Press PGDN to view a list of unassigned keys 
following the assignment list. 
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To assign a new key to a function, replace keyname with the name of the new key. 
The change does not take effect until you move the cursor to a different line. 


When you move the cursor, the line with the new assignment is highlighted. To 
make the assignment permanent, save the file by pressing SHIFT+F2 or by choosing 
the Save command in the File menu. This updates the TOOLS.INI file, where 
changes to key assignments are stored. 


To remove a key assignment, assign the unassigned function to the key. 


Using Advanced Editor Features 


Most of the standard editing features in PWB are intuitive and easy to use. How- 
ever, there are also many advanced editing options that allow you to customize 
and control the editor beyond simple menu commands. 


The PWB editor incorporates all of the powerful features found in the Microsoft 
Editor. You can set a variety of functions and switches to further customize the 
PWB editor and enhance its performance. A complete list of editor functions and 
settings is available in the online reference system. 


You can add new or altered functions and settings to the TOOLS.INI file so they 
are loaded when PWB starts, or you can enter them interactively while you are 
working in PWB. 


For example, to assign a key command interactively to the editor’s curdate func- 
tion, which enters the current date at the cursor, first press ALT+A. (The display 
Arg[1] appears at the left end of the reference bar to show that you have pressed 
ALT+A once.) Type the following into the argument dialog box (note that the 
dialog box does not appear until you have typed the first character): 


Curdate: SHIFI+CTRL+T 


Press ALT+= to assign the key to the function. 


Now when you press SHIFT+CTRL+T, the current date is inserted at the editor’s cur- 
sor position. 


For detailed information about advanced PWB features, refer to the Programmer’ s 
Guide and the online reference system. 


Assembling and Linking 


Reconfiguring the Editor 


PWB includes the BRIEF.INI file with key assignments that emulate the BRIEF 
editor. To use these key assignments, add the contents of this file to TOOLS.INI. 
You can also simulate command sets from other editors using the customization 

techniques described earlier. 


Running Other Programs 


One of PWB’s most powerful features is its ability to run other programs without 
exiting to the command line. The Customize Menu command in the Run menu lets 
you add any program to the Run menu, where you can execute it simply by click- 
ing its name. You can also specify any keystroke to run it directly. 


After selecting Customize Menu, click the Add button in the Customize Menu 
dialog box that appears. The dialog box lets you type all the information PWB 
needs to successfully execute the program: its name, directory, command-line 
arguments, and so on. Note that you can give the program any name you like on 
the command line, and you can specify that the program run in the background. 


Assembling and Linking 


PWB can handle all the details of assembling and linking (building) a program for 
you. You first tell PWB which source files constitute the program. PWB then 
creates a “makefile,” which specifies how these files are supposed to be as- 
sembled, compiled, and linked to create the final executable file. PWB already 
knows that .ASM files are to be assembled, .C files are to be compiled, and the re- 
sulting .OBJ files are to be linked, so it can handle simple projects automatically. 
Complex projects may require you to write your own makefile. 


Once the makefile is created, you build your project by selecting the Build com- 
mand. The makefile also speeds the build process with multimodule programs, 
since only those source files that have changed from the last build are reassembled 
or recompiled. 
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Building Programs in PWB 


This section shows how to build programs in the PWB environment. If you don’t 
have a program of your own, you might want to use the following program: 


; HELLO.ASM defines a string and calls the procedure PutStr to 
; display the text. PutStr is in a separate module PUTSTR.ASM. 


-MODEL small, c 


; Tell assembler PutStr's argument type and how to call PutStr: 
PutStr PROTO pMsg:PTR BYTE 


.DOSSEG 
. STACK 


.DATA 


msg BYTE "Hello, world.", 13, 10, ®@ ; Null-terminated string 


.CODE 


. STARTUP ; Initialize data and stack segments 


INVOKE PutStr, ADDR msg ; Call external procedure 


-EXIT @ ; Exit program 


END 


Note that there are new directives (such as .DOSSEG) and new constructs (such as 
INVOKE and PROTO) in this and the following procedure. MASM version 6.0 has 
a number of new features to make assembly-language programming more like pro- 
gramming in a high-level language, while maintaining the compact, fast-executing 
code assembly language offers. These features are explained in detail in the online 
reference system and in the Programmer’ s Guide. 


Saving a Program 


To save a source file, select the File menu and choose either Save or Save As. If 
the file is new or you choose Save As, a dialog box prompts you for a filename 
(see Figure 3.3). If you choose Save with an existing file, PWB automatically 
saves the file under the name listed in the title bar of the Source window. To save 
a copy of a file under a different name, choose Save As. (The older version of the 
file, with its original name, is not deleted or modified.) 


Assembling ang Linking 


| Beet Edit View Search Make Run Options Browse 
D :\MASM6ON\HELLO .ASM 
HELLO.ASM defines a string and calls the procedure PutStr to 
display the text. PutStr is in a separate module PUTSTR.ASM. 
Save As 


ile Name: (ESOS 


> Te} D:\MASM66 
File Hist: 


HELLO.ASM 


@ OK § <Cancel> < Yelp > 


> Exit program 


Fi=Help Enter Esc=Cancel Tab=Next Field BE 90001. 


Figure 3.3 Dialog Box for the Set Program List Command 


Type in the name of the source file, HELLO.ASM. Press ENTER or click the OK 
button to save the file with this name. 


Writing and Saving a Procedure 


HELLO.ASM calls the PutStr routine to display a message (in this case, 
Hello, world) onthe screen. You could add this routine to the HELLO.ASM 
file; but because it’s a procedure that could be used in other programs, you should 
put it in a separate file. 


Use the New command in the File menu to clear the screen. Type inthe PutStr 
routine that follows and save it in a file named PUTSTR.ASM: 
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; PUTSTR.ASM contains a procedure PutStr, which displays a 
; null-terminated string on the screen. 


-MODEL small, c 


. CODE 

PutStr PROC pMsg:PTR BYTE 
mov ah, @2h 
mov di, pMsg 
mov dl, [di] 
-WHILE (dl) 
int 2ih 
inc di 
mov di, [di] 
. ENDW 
ret 


PutStr ENDP 


END 


we we we we 


Address of string (near or far 
depending on model) is passed on 
the stack 

Display character function 


Load address in DI 
Load each character through [DI] 


DOS displays character 
Point to next character 
Load each character through [DI] 


Setting the Main Language and Build Options 


Before assembling the HELLO program, you must first specify the type of pro- 
gram you are building. Once you choose a main language and an initial build op- 
tion, you can change its settings using the MASM Options command from the 


Options menu. 


To specify a main language and an initial build option: 


1. Choose the Build Options command from the Options menu 


2. Choose the Set Main Language button 


3. Use the mouse or the ARROW keys to select “Assembler” from the list, and 


then press ENTER 


4. Choose the Set Initial Build Options button 


5. Use the mouse or the ARROW keys to select a build option from the list, and 


then press ENTER 


For the HELLO program, select the DOS EXE build option. 


Assembling and Linking 


Setting and Clearing the Program List 


Once you set the main language and initial build options, you need to set the pro- 
gram list. The Set Program List command in the Make menu tells PWB which 
makefile to use in building a program. It clears the current makefile setting, in- 
structs PWB to use the makefile you have specified, and specifies which Browser 
(.BSC) file is associated with the current project. 


Choose the Set Program List command from the Make menu. In the dialog box 
that appears, type the main program’s filename (HELLO), then press ENTER (see 
Figure 3.4). PWB automatically loads the .MAK file if it exists or asks you if you 
want to create it. 


File Edit View Search $XEV Run Options Browse 
D:\MASM60\PUTSTR.ASM 
PUTSTR.ASM contains a procedure PutStr, which displays a 
null-terminated string on the screen. 
Set Program List 
ile Name: CHELLO 


D:\MASM60 


File Dist: 


FILEDENO .MAK 
HELLO. MAK 

MATHDEMO .MAK 
MISCDEMO .MAK 


{ 1 Jse as a Non-PUB Makef ile 


@ OK § <Cancel> < Jelp > 


Figure 3.4 Dialog Box for the Set Program List Command 


If the makefile does not exist, PWB asks if you want to create a new makefile; 
answer Yes. The Edit Program List dialog box appears, listing all files in the cur- 
rent directory. Select the files you want to include in the project (in this example, 
HELLO.ASM and PUTSTR.ASM). It doesn’t matter in which order the files 
appear. 
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Keyboard > To select the files: 
1. Press TAB until the cursor is within the list box containing the directory of files 
(another box lists the directory names). 


2. Use the ARROW keys to move to the HELLO.ASM file. Press ENTER to add the 
filename to the program list. 


3. Repeat step 2 for PUTSTR.ASM. 
4. Once both filenames appear in the program list, press TAB until the Save List 


command button is highlighted, and then press ENTER. 


Mouse > To select the files: 
1. Click HELLO.ASM once; then click the Add/Delete button (or just double- 
click HELLO.ASM). 
2. Repeat step 1 for PUTSTR.ASM. 


3. Once both filenames appear in the program list, click the Save List command 
button to save the makefile. 


PWB automatically creates a makefile appropriate for the files you selected. You 
can edit the .MAK text file to change or add additional commands. 


If you want to create a new program or instruct PWB to “forget” the current pro- 
gram, use the Clear Program List command in the Make menu. This action clears 
the current program-list setting. You can then specify a new program to build 
using the Set Program List command. You should always clear the program list 
before starting work on a different project. 


Assembling and Linking HELLO.ASM 


The MASM Options command in the Options menu lets you control a variety of 
assembly options (see Figure 3.5). 
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Edit View Search Make Run 9D S0) Brouse 
D :\MASMGO\PUTSTR .ASM 
Macro Assembler Global Options 
Case Sensitivity Warn Level 
Preserve Case of Names in Jb ject File ( } Level 


igreserve Case of All User Identifiers ( ) Level 
Map All Identifiers to Dppercase (+) Level @ 
( ) Level §& 
X1 Marnings Treated as Errors 
] fjiny Memory Model 
1] ASM 5.1 Compatibility 
1 Emulator Fixups for Qloating Point 


Daf ines 
clude Paths 
dditional Options [ 


A 
< Set Debul] Options... > < Show Debug Options... > 
< Set Jelease Options... > < Show Release Options... > 


[ 
an | 
{ 
C 


@ ok § <Cancel> < Telp > 


the stack 


er Es 


Figure 3.5 Macro Assembler Global Options Dialog Box 


From within the Macro Assembler Global Options dialog box, you can use the Set 
Debug Options and Set Release Options buttons to easily create debug and release 
versions of your program. 


The Set Debug Options button displays a dialog box where you can set parameters 
for activities like generating list files and debugging. These settings also apply to 
programs built with the Debug Build option, which you select from the dialog box 
displayed by the Build Options command. Use debug settings when you are 
developing and actively debugging your program. When the Release Build option 
is checked in the Build Options dialog box, the parameters specified in the Set Re- 
lease Options dialog box apply. 


Similar debug and release options are also available for the linker with the LINK 
Options command in the Options menu (see Figure 3.6). You can display the op- 
tions in both the Macro Assembler Global Options and LINK Options dialog 
boxes using Show Debug Options and Show Release Options buttons. 
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See cee Options Bidtce 
D:\MASM6ONPUTSTR.ASM 
LINK Options 
LINK Debug Options 
%] CodeJieu 
crenental Link 
p File 
Pack KE file 
X1 Translate ee el Calls 
[X] Pack Sode Segments Wimit: [65499-] bytes 
C J Pack ata Segments 


] 
] 
] 
] 


[ 
[ 
[ 
[ 
C 


Bdditional Libraries [ 
Additional Options 


< Sho] Options... > 


Figure 3.6 LINK Options Dialog Box 


The Set Release Options button in the Macro Assembler Global Options dialog 
box offers the same choices as Set Debug Options, but Set Release applies them to 
a final version of the program. Use these settings when your program is com- 
pletely debugged and ready for release. 


Before building a program, make sure its name appears after the Compile File and 
Build commands in the Make menu. If the name does not appear after the Build 
command, choose the Set Program List command in the Make menu to set the 
makefile as the current project. 


To build the program, choose the Build command in the Make menu. If an as- 
sembly or link error occurs, the build terminates and the error appears in the 
Compile Results window. You can get information about unknown errors from 
the online reference system by selecting the error and pressing F1. In OS/2, you 
are notified of errors and asked if you want to see the assembly log. (If you want 
to view the assembly log when running PWB under DOS, you must select the 
Compile Results command from the View menu before starting assembly.) 


Debugging Programs 


Running the Program 


After the program is built, PWB adds the name of the executable file to the Ex- 
ecute command in the Run menu. Choose Execute to run the program. When the 
program is complete, press any key to return to PWB. 


Debugging Programs 


PWB has a variety of resources available for debugging programs. They range 
from simple assemble-and-link error messages to sophisticated source browsing 
and source- or assembly-level debugging. 


When assembly errors occur, the cursor moves to the line that caused the first 
error; a brief description of the error appears in the reference bar. Use the Next 
Error and Previous Error commands in the Search menu to move the cursor to 
lines where other errors occurred. 


To see a complete list of errors, choose the Compile Results command from the 
View menu. Move the cursor into the Compile Results window and use the Set 
Error command in the Search menu to select the error under the cursor as the cur- 
rent error. This command synchronizes the source and error windows so the 
source-code line containing the error appears in the active window. 


Use the Microsoft Advisor to display online help about the error. In the Compile 
Results window, move the cursor to the error number and press F1, or click the 
number with either mouse key. 


PWB incorporates a source-code browser and interfaces with the CodeView debug- 
ger. The Browser displays information about function and data relationships. 
CodeView is a window-oriented symbolic debugger that lets you step through your 
code and examine variables and data as the program executes. 


Using the Browser 


The Browser can search a database of selected files to get a list of references and 
definitions, to build a call tree and outline, or to create a list of relationships 
among program symbols. You can examine this material to see how your program 
is structured. Figure 3.7 shows how HELLO.ASM calls the PutStr procedure. 
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File Edit View Search Make Run Options Browse 
D:\MASM6O\HELLO .ASM 

> HELLO.ASM defines a string and calls the procedure PutStr to 

> display the text. PutStr is in a separate module PUTSTR.ASM. 


Q 
FUNCTION CALLED BY LIST 


eStartup: (HELLO .asm) 
PutStr: (HELLO .asm)[3] PutStr 


VARIABLE USED BY LIST 

_DATA: CHELLO .asm) (PUTSTR .asm) 
_TEXT: (HELLO.asm)}{[2] (PUTSTR.asm) £2] 
DGROUP : (HELLO.asm) [3] (PUTSTR.asm3[21 
HELLO .asm: 
msg : CHELLO .asm}{2] 
pMsg: PutStrf2Z] 
PUTSTR.asm: CHELLO.asm) 

: CHELLO .asm) 

R. 


RU 00001. 


Figure 3.7 Browser Information 


The commands on the Browse menu are referred to collectively as the PWB 
Source Browser. Before using these commands, you must define the database the 
Source Browser is going to search. 


® To define a database: 


1. Generate a program list using the Set Program List command from the Make 
menu. The files contained in the program list make up the database. 


2. Choose Browse Options in the Options menu. You must select the Generate 
Browse Information field in the dialog box to create the Source Browser 
database. The rest of the fields in this dialog box offer you choices of how to 
build the database; they are optional. 


3. Build your program using the commands from the Make menu. When you 
build the program, a file with the same program-list root name and a .BSC 
(Browser Source Cache) extension is created. This file contains reference infor- 
mation used by the Browser. 


Once you have completed these steps, the following Browse menu commands are 
ready for you to use: 
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m The Goto Definition command provides a list of symbols and variables that 
occur within include files and modules. You can immediately open the file at 
the line number where the definition of a symbol or variable appears by select- 
ing the OK button. 


m The Goto Reference command displays a list of files and line numbers where 
symbols and variables have been referenced in include files and modules. 


m The View Relationships command provides detailed information about various 
portions of your program. You can examine functions, macros, types, and vari- 
ables by their use, definition, or inclusion in include files and modules. 


w The List References command displays references to functions, macros, types, 
and variables. You can move the cursor to a reference and then use the Goto 
Definition or Goto Reference command to show occurrences of the reference. 


m The Call Tree command displays a tree structure of function calls within the 
_ program. 


For additional information about the Browser, refer to the online reference system. 


NOTE You can create a Browser information file with the ML (command-line) assembler 
using the /FR or /Fr option. This creates a .SBR file, which you must convert to a Browser- 
readable .BSC file with the PWBRMAKE.EXE utility. 


Debugging with the CodeView Debugger 


Once a program has been built, you can use the Microsoft CodeView debugger to 
step through the source code, displaying output, registers, and variables as each 
line is executed (see Figure 3.8). You can also set breakpoints and watchpoints to 
cause execution to pause at critical sections of code. From within CodeView, the 
Microsoft Advisor can provide online help about CodeView operation, options, 
and MASM keywords in the source code. Although you can call CodeView from 
the command line, PWB provides access to CodeView without exiting. See Chap- 
ter 15 in the Programmer’ s Guide for more information about using CodeView. 


NOTE CodeView version 3.12 is compatible with releases of OS/2 later than version 1.0. If 
you have problems exiting CodeView, you have either an older version of OS/2 or the wrong 
version of the DOSCALLS.DLL file. 


If you use CodeView from the 0S/2 DOS compatibility box, be sure the /S (Swap Screen in 
Buffers) option is set in the CodeView Options dialog box. If the option is not set, the mouse 
cursor is not displayed while you are debugging. 
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File Edit View Search Run Watch Options Calls 


 uem”socel Co:IP PUTSTR.asm (ACTIVE) 
: 10 


sgmnt WORD 
vid_conf ig ENDS 


Video_Conf vid_config <O, 1, 25, 80, 3, 4, 10> 


-CODE > Address of string (near or far 
PutStr PROC pMsg:PTR BYTE ; depending on model) is passed on 
: the stack 
ah, 92h ; Display character function 


di, pMsg > Load address in DI 
di, [dil 3 Load each character through [DI] 


> DOS displays character 
> Point to next character 
> Load each character through [DI] 


Figure 3.8 The CodeView Window 


Preparing a Debug Build 


It’s easy to create a debug version of a program so it can be examined with 
CodeView. 


Choose MASM Options in the Options menu; then select the Set Debug Options 
button. This dialog box contains a variety of settings for a debug build. Although 
most of the options can be set to your preference, you must check the CodeView 
option under the Debug Information heading. 


The CodeView Options command in the PWB Options menu provides a variety of 
choices for configuring CodeView. These include two-monitor debugging, mem- 
ory allocation, and selecting the number of lines on the screen. For now, use the de- 
fault settings initially displayed. 


For the assembler to build a program containing the necessary CodeView informa- 


_tion, you must check the Debug option, which is set in the dialog box displayed by 


the Build Options command in the Options menu. You must also select the 
CodeView option (which is on by default) in the Set Debug Options dialog box 
accessed from the MASM Options command in the Options menu. 


To demonstrate how CodeView works, set the debug options as listed above, then 
rebuild the HELLO.ASM program using the Rebuild All command in the Make 
menu. 


Debugging Programs 


Examining the Program 


After your program has been built with the appropriate debug options, choose the 
Debug command from the Run menu. PWB immediately transfers control to 
CodeView, loading the current project as indicated in the program list. 


When you switch from PWB to CodeView, the program appears in the Source win- 
dow. The Source command in the Options menu displays your program in one of 
the following ways: 


m As source code from your MASM source-code file. This is the default display. 


m As assembly language generated by CodeView disassembling the program’s 
executable file. 


m Asamix of these two, with the disassembled code following the correspond- 
ing source code. 


The mixed-code option is especially useful when your program contains macros or 
directives that generate code; you can see how the assembler converted them into 
machine instructions. 


In addition to showing source code, commands in the View menu show windows 
displaying memory, registers, and local variables. All windows are similar to PWB 
windows; they can be scrolled, sized, and closed. You can have multiple windows 
on one screen, displaying a variety of information. A list of shortcut keys and but- 
tons appears at the bottom of the screen. 


Setting Watch Expressions and Breakpoints 


A “watch expression” is a program variable that CodeView continually monitors. 
Watch expressions are displayed using the Watch command from the View menu. 
As the value of a variable changes, the value also changes in the watch window. 


To add a variable to the watch expression list, position the cursor anywhere within 
the variable and choose the Add Watch command from the Watch menu. You can 
also type the variable name in the dialog box. Remove watch expressions using the 
Delete Watch command from the Watch menu, or position the cursor on that ex- 
pression’s line in the Watch window and press CTRL+Y. 
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To set a watch variable in the HELLO.ASM file, use the cursor to highlight the 
pMsg _ variable in the CodeView Source window. Then choose the Add Watch 
command from the Watch menu. The pMsg variable appears in the Expression 
text box. Press END to position the cursor at the end of the name, and then type 

,S (so that CodeView displays the data at this address as a string). Press ENTER or 
click the OK button to add this variable to the Watch window. The Watch window 
gives a “Watch Expression Not in Context” error until you trace into the PutStr 
procedure. 


CodeView also incorporates a temporary watch option called Quick Watch. 
Highlight a variable in the Source window with the mouse or cursor. Choose the 
Quick Watch command from the Watch menu. A dialog box appears giving the 
current value of the variable. You can add any Quick Watch variable to the watch 
window using the Add Watch dialog box option. 


You can expand any structures or arrays that are set as watch expressions (iden- 
tified with a + in the Watch window) to show individual elements. Position the cur- 
sor on the variable name and either double-click the left mouse button or press 
ENTER (see Figure 3.9). 


File Edit View Search Run Watch Options Calls 


-list 
grade = 0x6008 
year = 0x005a 
idnum = 0x@064 ’d’ 
1B MBsourcel CS:1P student.asm_ (ACTIVE) 
STUDENT STRUCT 
grade WORD ? 
year WORD ? 
idnum BYTE ? 
STUDENT ENDS 


-DATA 


3: 
4: 
S: 
6: 
7: 
6: 
9: 


list STUDENT <6, 90, 100 > 
- STACK 
-CODE 
. STARTUP 


bx, OFFSET list ; Point to array of students 


a 
<F8=Trace> <F10=Step> <F5=Go> <F6=Window> <F3=Displa 


Figure 3.9 The Watch Window 


A “breakpoint” is an instruction that tells CodeView to interrupt execution at a cer- 
tain location or when an expression becomes true. 
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Use breakpoints to cause execution of the program to pause before an error occurs 
and to move quickly to a part of the program you want to trace. When CodeView 
stops at a breakpoint, you can single-step or trace through instructions until you 
find the problem. 


Set a breakpoint by positioning the cursor on the line at which you want the pro- 
gram to stop and then pressing F9. You can also choose the Set Breakpoint com- 
mand from the Watch menu. A dialog box presents a series of options for setting 
types of breakpoints. You can modify or delete breakpoints using the Edit Break- 
points command from the Watch menu. 


Set a breakpoint in the HELLO.ASM file by moving the cursor in the CodeView 
Source window to the line that reads 


INVOKE PutStr, ADDR msg 


From the Watch menu, choose the Set Breakpoint command. The number of the 
line the cursor appears on is displayed in the dialog box. Press ENTER or click the 
OK button to store the breakpoint. After the breakpoint has been set on a line, that 
line is highlighted. 


Running the Program Within CodeView 


CodeView offers several ways to run a program. You can let the program execute 
at full speed or view each line as it executes. Table 3.2 lists the CodeView run 
commands. 


Table 3.2 CodeView Run Commands 


Name Use Key 

Go Executes the program to the next breakpoint, error, or F5 
end of the program 

Trace Executes a single line F8 

Step Executes a single line, but doesn’t trace into functions F10 


Enter run commands by pressing the appropriate key or clicking the commands at 
the bottom of the screen. The Trace and Step commands highlight each line as it 
executes. The Go command simply executes (without highlighting) until the pro- 
gram stops at an error, a breakpoint, or the end. If you choose the Animate option 
for the Go command, CodeView highlights each line as it executes. To force execu- 
tion to start at the beginning of the program, use the Restart command in the Run 
menu. 
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You can either single-step through a program or use the Animate command in the 
Run menu to step through the program automatically, highlighting each line as it 
proceeds. 


If a program requires arguments to be passed from the command line, these argu- 
ments can be entered with the Set Runtime Arguments command from the Run 
menu. 


Running HELLO.EXE 


To look at some of the CodeView commands while running HELLO.EXE, make 
the Source window active by pressing F6 or by clicking its title bar. Then choose 
the Restart command from the Run menu. Restart clears memory and prepares the 
program to start execution at STARTUP. 


Press F5 or choose the Go button at the bottom of the screen to start the program. 
The program executes until it reaches the breakpoint you set at the INVOKE 
directive. 


If you press F8 or the Trace button, CodeView executes and displays each state- 
ment of PutStr. If you use F10 or the Step button, CodeView executes PutStr 
without showing each step. 


The variable pMsg is actually a pointer, so no value is displayed until you ex- 
ecute the PutStr procedure. As you step through PutStr, the display 
switches to the output screen each time a character is written to the screen. 


Because pMsg is also a local variable, it appears in the Local window with all 
variables local to PutStr. You can expand local data in the Local and Watch 
windows by double-clicking it. 


Press F10 to finish stepping through the program. A dialog box informs you that 
the program has completed execution normally. Press ENTER to clear the dialog 
box and complete your debugging session. 


Debugging HELLO.EXE 
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To see how CodeView deals with a bug, add these statements at the end of the 
source code for this program: 


mov ax, @FFh 
int 21h 


Set the appropriate debug options, rebuild the program, and return to CodeView. 


Getting More Details 


Use F8 (Trace command) to execute the program. An execution error occurs when 
the INT instruction is executed, because there is no interrupt function correspond- 
ing to OFFh. 


Getting More Details 


PWB, the assembler, the linker, NMAKE, and CodeView have additional features 
and options beyond the scope of this introduction. 


Refer to the Programmer’ s Guide for information about PWB, NMAKE, 
CodeView, and other tools. Refer to the Reference for a quick reference to all com- 
mands and options for the applications included with MASM. 


You can access additional information about any component of the Professional 
Development System through the Microsoft Advisor online reference system. For 
a description of the online reference system, see Chapter 4 of this manual. 
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Chapter 4 


Using the Online Reference 
system 


The Microsoft Macro Assembler (MASM) offers two types of online reference 
systems: 


m The Microsoft Advisor, accessible from within the Programmer’s WorkBench 
(PWB) and CodeView environments 


m The QuickHelp program, accessed from the OS/2 or DOS command line 


Both reference systems provide the same information about important features of 
the Professional Development System, including language-specific information 
and information about utilities like the CodeView debugger and PWB. 


The first section of this chapter, “Structure of the Microsoft Advisor,” outlines the 
structure and contents of the online reference database. The second section, “Navi- 
gating the Microsoft Advisor,” takes you on a quick tour of the system. The third 
section, “Using QuickHelp,” explains how to use the QuickHelp program and how 
it differs from the Microsoft Advisor. 


Structure of the Microsoft Advisor 


The Microsoft Advisor displays a table of contents of all online reference files 
available with the Professional Development System. Choose the Contents com- 
mand from the Help menu to display the table of contents. From the table of con- 
tents you can select any topic you want to know more about. Figure 4.1 shows the 
table of contents screen. 
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File Edit View Search Make Run Options Brouse 
Help: Microsoft Advisor 


Index? <Back> 
—Hicrosoft Advisor Help System 


Edit/Debug Languages APIs 


Programmer’ s WorkBench> 4C Language> 408/72 Overview 

4CodeView> 4C Libraries> 4087/2 API> 
fAssemb lu> indous API> 
BASIC 4Netuork APIP 
COBOL 


4Errors Help> 4FORTRAN> “PUB Extensions> 


icrosoft Utilities onnand Line 


<LINKD- <LIBP 4C Compiler> Custom Help> 
“<NMAKED <BIND> “Macro Assembler> 

“HELPMAKED <ILINK> “BASIC Compiler> 

<QH> “COBOL System 

4Misce 1 laneous> “FORTRAN Compilerb> Using Help> 


Figure 4.1 Table of Contents of the Online Reference 


The Microsoft Advisor also displays indexes for each online reference file. Choose 
the Index command from the Help menu to display the help topics, and then select 
the topic whose index you want to search. The alphabet bar at the top of the index 
screen allows direct access to a list of the index topics starting with the letter you 
select. 


Navigating through the Microsoft Advisor 


You request information about a topic in a window by positioning the cursor over 
it and pressing F1 or clicking the right mouse button once. The help system then 
searches through the help files for information about the topic. If it finds the topic, 
the help system displays information in the Help window. If help cannot be found 
for a particular word or symbol, a message informs you that no information is as- 
sociated with the topic. Sometimes a topic with the same name occurs in several 
help files. In such cases, a dialog box is displayed in which you can select the con- 
text of the topic. 


Using the Help Menu 


The Help menu provides full access to the online reference system. All these com- 
mands display information in the Help window: 
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Command 


Contents 


Index 


Topic: 


Help on Help 


Next 


File Edit View Search 


——Nicrosoft Advisor 


Edit/Debug Indexes 


Language Indexes 


Utilities Indexes 


Command Line Indexes 


Description 


Displays a global contents screen of the topics in the help 
files. 


Displays a global index list and provides access to indexes 
for all components of the online reference system. (See 
Figure 4.2.) 


Provides information about the topic the cursor is currently 
on. If information about the topic is available, the topic’s 
name is appended to the Topic: command. Otherwise, this 
menu option is grayed. 


Displays information about using the online reference sys- 
tem itself. 


Locates the next occurrence of a topic name and displays 
the information associated with it. Use this command to get 
additional information about a topic that appears in more 
than one help file. 


Make Run Options Browse 
Help: Microsoft Advisor Indexes 
4Contents> 


: List of Indexes 


Programmer’ s WorkBench> 
<CodeView> 


4C Language and Libraries> 
4Assenbler> 

BAS ICP 

<FORTRANY 

COBOL 


4C Compiler> 
“Macro Assembler> 
“BASIC Compiler> 
‘FORTRAN Conpiler> 
<COBOL Compiler> 


<LINK> 
41L INK 


Figure 4.2 Global Index of the Online Reference 


Using the F1 Key and the Mouse 


The F! key displays 


information about the MASM keyword or operator the cursor 


is positioned on. You can also use the Fi key to directly access information about 
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the menu command currently highlighted or the PWB dialog box currently 
displayed. 


The mouse can perform the same function. Position the mouse cursor on the com- 
mand, dialog box item, or keyword, and click the right mouse button. 


If the help system cannot find help for a particular word or symbol, a message tells 
you so. Sometimes a topic with the same name occurs in several help files. In such 
cases, a dialog box appears in which you can select the context of the topic. 


Figure 4.3 shows the help information for the Cut command from the Edit menu. 


bE View Search Make Run Options Browse 
Help 
4Example> 4Up> <Contents? <Index> <Back> 


Shortcut key: Shift+Num- 


Use the Cut command to delete the selected (highlighted) text from 
the active window and copy it to the Clipboard. The default 
highlight is one character, which means that without highlighting 
any text, the current cursor location is always highlighted. 


Once a block of text is in the Clipboard, you can use the 4Paste> 
command, or press Shift+Num+, to insert it into the active window. 
Text is inserted at or below the current cursor location. The cut 
(copied) text is still in the Clipboard. It can be pasted into 
another location in the file. 


See: «Delete Function> 


<General Help> <Fi=Help> <Alt=Menu> 


Figure 4.3 Help on the Cut Command 


Using Hyperlinks 
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Hyperlinks are cross-references that connect related topic information. Hyperlinks 
can be marked explicitly, or they can be implicit. 


Hyperlinks marked with the 4 and > characters are called “buttons.” You can 
move through the online reference system using these buttons. Press TAB to move 
the cursor to the next hyperlink button within the current Help window. SHIFT+TAB 
moves the cursor back to the previous button. Typing any letter moves the cursor 
to the next button that begins with the letter. Holding SHIFT down and typing a let- 
ter moves the cursor backward. 


Navigating through the Microsoft Advisor 


The Microsoft Advisor also recognizes MASM keywords, constants defined by 
MASM, and similar identifiers as hyperlinks, but they are unmarked. These un- 
marked hyperlinks are recognized wherever they appear in the help text or in your 
source code. You cannot move to an unmarked hyperlink with the TAB key. 


You can access a hyperlink from the keyboard or with the mouse by doing one of 
the following: 


m= Move the text cursor to the hyperlink and press F1 


m Position the mouse cursor over the hyperlink; then click the right mouse button 
or double-click the left mouse button 


You can also execute highlighted button hyperlinks by pressing ENTER or the 
SPACEBAR. 


Any of these actions displays information about the topic the cursor is positioned 
on. If the topic isn’t a hyperlink, a message informs you that no information on the 
topic could be found. 


NOTE CodeView uses the right mouse button differently in the Source window. Clicking 
the right button in the Source window executes the program to the line the mouse was 
clicked on. However, once the Help window is displayed, clicking the right mouse button 
selects hyperlinks. 


Using Help Windows and Dialog Boxes 


The Microsoft Advisor displays information in windows or dialog boxes. Help 
windows and dialog boxes function the same as other windows and dialog boxes 
found in PWB and CodeView. For a description of windows and dialog boxes, 
refer to Chapter 3, “Using the Programmer’s WorkBench.” 


Using the Help Window 


The Help window displays tables of contents, indexes, and information about 
selected topics. Some screens of information are larger than the Help window; you 
can view information beyond the window borders with the scroll bars or the cursor- 
movement keys. The —-@— symbol marks the end of information in the Help 
window. 


Navigating with Hyperlink Buttons At the top of the Help window is a 


row of buttons that is useful for moving through the reference system: 
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Button Description 


<Up> Moves upward in the hierarchy of help screens. Since informa- 
tion is ordered from the general to the specific, this button 
takes you to more general information about the subject. 


<4Contents> Displays the table of contents. This button always returns you 
to a known point in the online reference 
system. 

4Index> Displays the index list. Selecting an item from the list displays 


the index for that category. 


<Back» Moves to the last online reference screen you viewed. 


Frequently, screens about a particular topic are grouped together in a help file. 
Press CTRL+F1 to display information about the next topic in the help file. 


Viewing the Previous Help Screen = The Microsoft Advisor remembers 
the last 20 help screens you’ve accessed. To return to a previous screen, use the 
<Back» button, or hold down the ALT key and press F1 as many times as necessary 
to return to the screen you want to see. The help screen that appears is active; you 
can ask for help on any of its hyperlinks or topics. 


You can always return to the global contents by pressing SHIFT+F1. 


Copying and Pasting Information You can easily copy any text that ap- 
pears in the Help window to another window. For example, to test an example pro- 
gram in the Help window, just copy it to the Source window and assemble it. 


Keyboard ® To copy and paste, follow these steps: 


1. Move the cursor to the beginning of the text you want to select. Hold down the 
SHIFT key and move the cursor to the end of the desired text. The text is now 
highlighted. 


2. Execute the Copy command: press ALT to activate the menus, E (Edit), then C 
(Copy). Note that the menu lists the shortcut command (CTRL+INS), which you 
can substitute for ALT+E, then C. 


3. Press F6 to switch to another window. Position the cursor where you want to in- 
sert the text and execute the Paste command: ALT+E, then P; or use the 
SHIFT+INS shortcut. The text from the Help window is inserted at the current 
cursor position. 


Navigating through the Microsoft Advisor 


Mouse > To copy and paste, follow these steps: 


1. Click the left mouse button and drag the cursor (hold down the button while 
moving the mouse) to select the text you want to copy. 
2. Choose Copy from the Edit menu (or press CTRL+INS). 


3. Move the mouse cursor to the location where you want to insert the text, and 
click once. Then choose Paste from the Edit menu. The text from the Help win- 
dow is inserted at the current cursor position. 


Closing the Help Window = To close the active Help window and return to 
the Source window, do one of the following: 


m Press ESC 


m Click the Close button in the upper-left corner of the window with the left 
mouse button 


Using Help Dialog Boxes 


Help dialog boxes contain information about menu commands and their dialog 
boxes. A help dialog box differs from a Help window in that it is displayed over 
the Source window and any other open windows. You must close a help dialog 
box before you can execute menu commands. Clicking the Cancel button in the 
lower-right portion of the dialog box closes the help dialog box. 


To view information about any PWB dialog box, do one of the following: 


m Press Fl 


m Click the help button in the dialog box with the left mouse button 


Either of these commands causes a help dialog box to appear. To close a help 
dialog box, do one of the following: 


mw Press ESC 


m Click the Cancel button in the lower-right portion of the dialog box with the 
left mouse button 
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Accessing Different Types of Information 
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This section presents some ways to access the different types of information avail- 
able within the online reference system. 


Keyword Information 


To get information about any keyword, operator, or symbolic constant, first dis- 
play the appropriate index for the keyword. Then select the keyword’s first letter 
from the index, scroll down the list of entries, and select the topic hyperlink. If you 
know the exact name of a keyword, it may be quicker to type it in the Source win- 
dow and press F1. 


You can also view information about keywords using the arg command. Type the 
keyword in the arg command dialog box. Then press F1. If you have the arg func- 
tion assigned to alt+a, the following displays help about the ADC (add with 
carry) command: 


alt+ta ADC Fl 


Figure 4.4 shows the information screen that then appears. 


When information about a keyword is shown in the Help window, additional 
hyperlink buttons may be displayed: 


m <Detail> provides a detailed explanation of the keyword. When the informa- 
tion is displayed, the button changes to ¢€Summary?>. Click this button to return 
to the summarized information about the keyword. 


m <4Example> displays MASM source code that provides an example of how the 
keyword is used. 


m <Key> explains symbols used in instruction encodings. 


Navigating through the Microsoft Advisor 


File Edit View Search Make Run Options Browse 
Help: ADC Instruction 
4Detail> <Key> <Example> 


Title: Add with Carry 
Syntax: ADC dest,src 
See also: ADD, SUB, SBB 
Description: 


Adds the source operand, the destination operand, and the value of 
the carry flag. The result is assigned to the destination operand. 


Use this instruction to add the more significant words that must 
be added in multiple steps. Use the ADD instruction to add the 
least significant words. 

-¢-— 


Figure 4.4 Help on the ADC Command 


Topical Information 


The online reference system is useful when you want an overview of available ref- 
erence topics or when you have only a general idea of what information you need. 
Start with the global contents screen and select any hyperlinks that relate to the 
topic. Then move through the hyperlinks until you locate the information you 
need. 


Menu and Dialog-Box Information 


You can get information about any menu command or dialog box by pressing F1 
when the menu command is highlighted or when the dialog box is displayed. 


Error Information 


The Microsoft Advisor provides information about assembler and linker error 
messages. 
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Keyboard )> To find the meaning of an error message: 


1. Press F6 to move the cursor to the error window 


2. Position the cursor on the error number and press F1 


To find the meaning of an error message: 


1. Position the mouse cursor on the error number 


2. Click the right mouse button 


To get help about error messages directly from the PWB Source window, type the 
arg command with the error number and its alphabetic prefix, and then press F1. 


Specifying Temporary Help Files 


You can instruct the Microsoft Advisor to search help files that you specify before 
searching the help files specified in the HELPFILES environment variable. For 
example, you may want to access the C help files first when writing a mixed- 
language program. 


Select the Environment command in the PWB Options menu. Type the path for 
the help files you want searched first in the text box that appears. These files are 
searched first only during your current session. 


Using QuickHelp 
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QuickHelp is a separate utility that works like the Microsoft Advisor. It displays in- 
formation in the same way and can access any Microsoft Advisor help file. Use 
QuickHelp if you use an editor other than PWB, or if you prefer to use command- 
line utilities. QuickHelp also supplies convenient access to help when you aren’t 
running PWB. 


The following sections explain how to call QuickHelp from the command line. 
You can use these same command-line calls to access QuickHelp from within any 
program that lets you pass commands to DOS or OS/2. 


Using QuickHelp 


Entering and Exiting QuickHelp 


If you installed documentation files during SETUP, you can run QuickHelp by typ- 
ing QH at the DOS or OS/2 command line. You can also specify the name of an 
application, such as 


QH LIB.EXE 
To get QuickHelp about the mov command, type 
QH mov 


If your editor supports macros, you can write a macro that reads the desired help 
topic from the editor’s command line or from the text-entry window, then appends 
itto QH and passes the result to the operating system. 


QuickHelp can also display information about run-time errors. Type the error num- 
ber with its alphabetic prefix after the QH command at the DOS or OS/2 command 
line. 


To exit QuickHelp, choose the Exit command from the File menu. 


Using /HELP 


You can get immediate information about major components of MASM by using 
/HELP. 


For example, to learn about the LIB utility, type 
LIB /HELP 


QuickHelp immediately displays information about LIB. 


Specifying Help Files 


QuickHelp searches for .HLP files according to a few simple rules. Understanding 
these rules helps you quickly access only the .HLP files you want. The more 
specific the search, the faster QuickHelp starts. 


You tell QuickHelp which .HLP files to open by specifying files or directories on 
the command line or in environment variables. To save time, most programmers 
specify commonly used .HLP files in the HELPFILES or QH environment 
variables. 
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You can specify either an entire directory or an individual file. If you specify a 
directory, QuickHelp opens every .HLP file in that directory. 


QuickHelp searches for .HLP files in the following order: 
1. If you specify a .HLP file or directory on the command line, QuickHelp first 
searches that file or directory. . 


2. QuickHelp next searches for files and directories specified in the HELPFILES 
and QH environment variables. 


3. If you do not specify any .HLP files on the command line, and QuickHelp 
cannot find any .HLP files in the HELPFILES and QH directories, 
QuickHelp searches the following directories and environment variables in 
the order shown: 
c:\gh 
DPATH 


PATH 
BOOKSHELF (0S/2 only) 


Note that QuickHelp does not search the current directory unless you specify that 
directory in one of the environment search paths. 


The List Database command from the File menu displays a list of currently open 
help files. To open additional help files 


m Choose the Open Database command from the File menu. 


m ‘Type in the fully qualified pathname of the help file to be opened in the dialog 
box that appears. You can specify all help files in a directory by typing *.HLP. 


m Press ENTER or click the OK button with the left mouse button. 
To close an open help file 


m Choose the Close Database command from the File menu. 


m Use the mouse or keyboard to select the help file you want to close from the 
list of help files displayed in the menu. 


Using QuickHelp 


Displaying a Topic 


You can view information about a topic by using the Search command from the 
View menu. When topic information is displayed, it is shown in the same format 
as information presented by the Microsoft Advisor. 


To display a topic from any of the open help files: 


1. Choose the Search command from the View menu. 


2. Type in the topic you want information on in the Search dialog box (the search 
is not case-sensitive). 


3. Press ENTER or click the OK button with the left mouse button. 


QuickHelp begins searching for the topic in the open help files. If the topic cannot 
be found, a dialog box informs you that the search failed. If the search is success- 
ful, information about the topic is displayed in the QuickHelp window. 


Navigating through the Topics 


A series of commands in the View menu allows you to display topics selectively. 
These commands include the following: 


Command Description 


View History Displays a list of all of the topics that have recently been dis- 
played. To view a topic in the list, select it and click the right 
mouse button, or press ENTER. 


View Last Displays the last topic you looked at. 
View Back Moves backward one topic in the help file. 
View Next Displays the next topic in the help file. 
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Using the QuickHelp Window 


The QuickHelp window (see Figure 4.5) is similar in function to the Microsoft 
Advisor Help window, described earlier in this chapter. Information that doesn’t 


fully fit in a window can be scrolled, and hyperlinks are used to display additional 
information. 


PYile Wiew sateyories Geferences Waste Mptions 1011/14033 
4Example> 


4Up> <Contents> <Index> <Backr T 


Syntax: @SizeStr (string) 
name SIZESTR string 


See also: INSTR, SUBSTR, CATSTR, TEXTEQU, angle brackets (<>) 


Description: 


The @SizeStr macro function returns the length of a string in 
characters. The SIZESTR directive performs the same function but 
assigns the result to <name>. A zero indicates a null Cempty) 
string. These two lines are equivalent: 


name length TEXTEQU @SizeStr (<Denise>) 
namelength SIZESTR <Denise> 


snamelength is 6 


<name> is a unique symbolic name. <string> must be a “text item>. 
-o~ 


Figure 4.5 QuickHelp Window 


Copying and Pasting in QuickHelp 


In order to transfer information, you must first specify a new file with the Rename 
Paste File command from the File menu. Once the file is specified, choose either 
the Current Window or the Current Topic command from the Paste menu to trans- 


fer the text to that file. Be sure to specify a new file when you paste, since Quick- 
Help overwrites text in an existing file. 


More About QuickHelp 


In addition to the features described above, QuickHelp has a variety of other op- 
tions, such as changing the appearance of the Help window, searching for text 
within topics, and controlling the function of the right mouse button. 
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To learn more about QuickHelp features, refer to the Reference for a list of Quick- 
Help options. For online information, make sure the QH.HLP file is loaded, then 
do one of the following: 


m Press Fl to view QuickHelp’s online reference 


m Choose a menu command and press F! or click the right mouse button to get in- 
formation about the command 
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Index 
: 


Anchors in text files, 37 
ASMEX environment variable, 17 
Assembling and linking 
Browser command-line options, 51 
build options, 44 
building programs, 41-42 
debug build, 52 
debug options, 47-48 
program list 
clearing, 45 
setting, 45 
release options, 47-48 
running programs, 46 
AUTOEXEC.BAT, modifying, 17 


Bookmarks in text files, 37 
Bound software, 15 
Breakpoints, setting, 54 
BRIEF. INI, 41 
Browse menu, 50 
Browser. See Source Browser 
Buffers parameter in CONFIG.SYS, 18 
Build options, setting, 44 
Buttons 

command, 34 

hyperlink, 62 

option, 33 


C 


Check boxes, 33 

CodeView 
breakpoints, setting, 54 
configuring extended memory, 20 
debug build, 52 
DOS compatibility box, 51 
examining programs in, 53 
executing programs in, 55 
generating information for, 51 


CodeView (continued) 

mouse buttons, use of, 63 

OS/2, 51 

Quick Watch option, 54 

run commands, 55 

Source window, 53 

using, 51, 56 

watch expressions, 53 
Command buttons, 34 
Compiling Results command, 49 
COMNFIG.SYS, modifying, 18 
Configuration files, 17 


D 


Debug options, 47 
Debugging, 49, 51-56 
Dialog boxes 
described, 32 
online reference, 65 
Directories 
bound-mode, 15 
protected-mode, 15 
real-mode, 15 


E 


Editor, PWB 
advanced features, 40 
anchors, setting, 37 
blocks, defining, 36 
bookmarks, setting, 37 
changing settings, 39 
cursor, moving in, 35-36 
customizing, 39, 41 
key assignments, changing, 39 
macros, creating, 38 
reconfiguring, 41 
saving files, 42 
searching and replacing, 37 
text-selection modes, 36 
writing and saving procedures, 43 
Environment variables, 16—17 
Errors, getting help on, 67 
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Index 


F Memory 
extended, configuring, 20-21 
Fl key, 61, 67 MASM, required for, 2 
Features, new, 3 Menus 
Files parameter in CONFIG.SYS, 18 Browse, 50 
choosing commands, 31 
H closing, 32 
Help, 60 
Hard disk, choosing, 15 Make, 46, 48, 50 
Help. See Online reference system Options, 44, 47, 50, 52 
Help files, specifying, 69 shortcut keys, 32 
Help information View, 49, 53 
copying and pasting in QuickHelp, 72 Watch, 53, 55 
copying and pasting with Microsoft Advisor, 64 Microsoft Advisor. See Online reference system 
Help menu ML.EXE, 14, 51 
commands, 60 Mouse support, 15 
using, 35, 60 MSHELP.DLL, 18 
HELPFILES environment variable, 17, 68 
HIMEM.SYS, 18, 20 N 


Hyperlinks, 62-63 
New features, 3 


| NEW-CONE.SYS, 17 
NEW-VARS.BAT, 17 
INCLUDE environment variable, 17 NEW-VARS.CMD, 17 
INIT environment variable, 17 Next Error command, 49 
Installing MASM 
See also SETUP.EXE 0 
mouse driver, copying, 15 
operating system, choosing, 13 Online reference system 
Programmer’s WorkBench, 14 See also QuickHelp 
accessing, 60 
K copying and pasting text, 64 
dialog boxes, 34, 65, 67 
Keyboard, changing assignments, 39 error information, 67 
Keys, shortcut, 32 Help menu, 34 
Help window, closing, 65 
hyperlinks 
L Back button, 64 
LIBPATH environment variable, 18 Contents, © 
Linking, 41 defined, 62 


Index button, 60, 64 

keyword information, 66 

Up button, 64 

M keyword information, 66 

menu information, 34, 60, 67 
previous help screen, viewing, 64 
temporary file, specifying, 68 
topical information, 67 

using mouse in, 61 


List boxes, 33 


Macros, creating, 38 

Make menu, 48, 50 
Makefile, 41 

MASM.EXE, installing, 14 
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Index 


Operating systems 
choosing, 13 
DOS 
defined, 1 
selecting during SETUP, 13 
setting up directories in, 15 
OS/2 
defined, 1 
selecting during SETUP, 13 
setting up directories in, 15 
Option buttons, 33 
Options menu, 44, 47, 50, 52 


P 


PATH environment variable, 17 
Previous Error command, 49 
Procedures, writing and saving, 43 
Program list 
clearing, 45 
setting, 45 
Programmer’s WorkBench (PWB) 
assembling programs in, 41 
Browser, accessing from, 49 
building programs in, 41-42 
customizing, 19, 39, 41 
debugging in, 49 
described, 4, 6—7 
Editor settings, 19, 39 
features, 23 
help, getting, 34, 63 
installing, 14 
macros, writing, 38 
menu commands, choosing, 31 
menus, 26, 31 
options, setting, 19 
screen, illustrated, 25 
source files, specifying, 24 
startup options, 24 
text, selecting, 36 
using, 23 
Protected-mode directories, 15 
PWB. See Programmer’s WorkBench 
PWB Windows. See Windows 


Q 


QH environment variable, 17 
QuickHelp 
See also Online reference system 
copying and pasting, 72 
described, 59 


QuickHelp (continued) 
entering and exiting, 70 
error information, 69 
/HELP, 69 
.-HLP files, specifying, 69 
navigating through topics, 71 
topics, searching for, 71 
using, 68 
window, 72 


R 


RAMDRIVE program, 21 
Real-mode directories, 15 
Release options, 47 

Run menu, 41 


Ss 


Saving files, 42 
Searching and replacing, 37 
Set Error command, 49 
SETUP.EXE 
changing your response, 13, 16 
described, 11 
file compression, 11 
location on disks, 11 
prompts, responding to, 13 
running, 11 
system-configuration files, 17 
Shortcut keys, 32 
SMARTDRYV program, 21 
Source Browser 
commands, 51 
defining databases, 50 
generating information for, 50-51 
PWBRMAKE.EXE, 51 
using, 49 
STARTUP.CMD, modifying, 17 
System configuration, 17 
System requirements, 2 


T 


TEMP environment variable, 17 
Text boxes, 33 
Text selection, 36 
TOOLS. INI 
macros saved in, 39-40 
modifying, 19, 40-41 
TOOLS.PRE, 17-18 
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V 


View menu, 49, 53 


W 


Watch menu, 53, 55 
Windows, PWB 
components, 25 
described, 24 
Help 
closing, 65 
using, 63 
QuickHelp, using, 72 
Writing and saving procedures, 43 
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